Skip to content

docs: use annotationProcessorPaths so query types generate on JDK 23+ - #1896

Merged
velo merged 1 commit into
masterfrom
docs-annotation-processor-paths
Aug 19, 2026
Merged

docs: use annotationProcessorPaths so query types generate on JDK 23+#1896
velo merged 1 commit into
masterfrom
docs-annotation-processor-paths

Conversation

@velo

@velo velo commented Aug 19, 2026

Copy link
Copy Markdown
Member

Fixes #1880.

The documented maven-compiler-plugin setup does not generate query types. I reproduced it on JDK 25 and JDK 21 with a minimal one-entity project.

What was wrong

The docs put querydsl-apt in the compiler plugin's <dependencies> block. That populates the plugin's classloader, not javac's annotation processor path, so the processor is never discovered. The build exits BUILD SUCCESS with no warning and no Q classes.

The reporter attributed this to implicit annotation processing being disabled in JDK 23. That is not the cause for this config — it fails on JDK 21 too, and adding <proc>full</proc> alone does not rescue it:

Config JDK 21 JDK 25
apt in plugin <dependencies> (what the docs said) 0 0
... plus <proc>full</proc> 0
apt as a project dependency (what the examples do) 1 0
... plus <proc>full</proc> 1
annotationProcessorPaths + <proc>full</proc> 1

So there were two independent breakages: the documented config never worked, and the project-dependency style used by the examples regressed on JDK 23+. annotationProcessorPaths + <proc>full</proc> fixes both, and keeps the processor off the compile and runtime classpath.

Changes

Converted every querydsl-apt snippet in docs/ to annotationProcessorPaths with <proc>full</proc>, and added a note explaining the JDK 23+ behaviour to the JPA tutorial and the code generation guide.

Two extra fixes found while verifying each classifier:

  • docs/tutorials/hibernate.md said to configure HibernateAnnotationProcessor but showed <classifier>jpa</classifier>, which selects JPAAnnotationProcessor. Corrected to hibernate, with hibernate-core added to the processor path (it is test scope on querydsl-apt, so it is not resolved transitively).
  • docs/tutorials/mongodb.md needs morphia-core (provided scope) and querydsl-mongodb on the processor path. Without them the build fails with NoClassDefFoundError: dev/morphia/annotations/Entity and then ClassNotFoundException: com.querydsl.mongodb.Point.

jakarta.persistence-api is not required on the processor path — it is a compile-scope dependency of querydsl-apt and resolves transitively — so it has been dropped from the JPA snippets rather than carried over as the issue suggested.

Verification

Every snippet was executed as a real Maven build on JDK 25, each generating the expected query type:

Classifier Processor path Result
jpa querydsl-apt:jpa QPerson
hibernate + hibernate-core QPerson
general querydsl-apt:general QCat
morphia + morphia-core, querydsl-mongodb QDog

The compilerArgs variant in the code generation guide was also verified to still apply alongside annotationProcessorPaths.

Docs-only change; no source or build files touched.

🤖 Generated with Claude Code

Signed-off-by: Marvin Froeder <velo.br@gmail.com>
@velo
velo merged commit a565d3c into master Aug 19, 2026
4 checks passed
@velo
velo deleted the docs-annotation-processor-paths branch August 19, 2026 17:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

JPA Maven setup in docs no longer works on JDK 23+; need update to annotationProcessorPaths

1 participant