From c3473c790f159be5913ac2c953ea00ec32fdb455 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Thu, 26 Jun 2025 17:45:34 +0200 Subject: [PATCH 1/9] Starting compiler plugin annotation processing --- .../plugin/compiler/AbstractCompilerMojo.java | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java index f935c8c57..c85d471c2 100644 --- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java +++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java @@ -278,20 +278,26 @@ final Charset charset() { protected String compilerArgument; /** - * Whether annotation processing is performed or not. - * If not set, both compilation and annotation processing are performed at the same time. + * Configures if annotation processing and/or compilation are performed by the compiler. * If set, the value will be appended to the {@code -proc:} compiler option. - * Standard values are: + * + * Possible values are: * * - * Prior Java 21, {@code full} was the default. - * Starting with Java 21, the default is {@code none} unless another processor option is used. + * The default value depends on the JDK used for the build. + * Prior to Java 22, the default was {@code full}, rso annotation processing and compilation were executed without explicit configuration. + * + * For security reasons, starting with Java 23 no annotation processing is done if neither + * any {@code -processor}, {@code -processor path} or {@code -processor module} are set, or either {@code only} or {@code full} is set. + * So literally the default is {@code none}. + * It is recommended to always provide the annotation processors you want to execute instead of using the {@code proc} configuration, to ensure that only desired processors are executed and not any "hidden" (and maybe malicious). * * @see #annotationProcessors + * @see Inside Java 2024-06-18 Quality Heads up * @see javac -proc * @see javac Annotation Processing * @since 2.2 From da95c9a0dd4b6e0d64d44bad60187e33f81b945c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Fri, 27 Jun 2025 21:55:43 +0200 Subject: [PATCH 2/9] Add documentation --- .../plugin/compiler/AbstractCompilerMojo.java | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java index c85d471c2..0b2c27b81 100644 --- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java +++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java @@ -18,15 +18,6 @@ */ package org.apache.maven.plugin.compiler; -import javax.lang.model.SourceVersion; -import javax.tools.DiagnosticListener; -import javax.tools.JavaCompiler; -import javax.tools.JavaFileManager; -import javax.tools.JavaFileObject; -import javax.tools.OptionChecker; -import javax.tools.Tool; -import javax.tools.ToolProvider; - import java.io.BufferedReader; import java.io.BufferedWriter; import java.io.File; @@ -51,7 +42,14 @@ import java.util.jar.JarFile; import java.util.jar.Manifest; import java.util.stream.Stream; - +import javax.lang.model.SourceVersion; +import javax.tools.DiagnosticListener; +import javax.tools.JavaCompiler; +import javax.tools.JavaFileManager; +import javax.tools.JavaFileObject; +import javax.tools.OptionChecker; +import javax.tools.Tool; +import javax.tools.ToolProvider; import org.apache.maven.api.JavaPathType; import org.apache.maven.api.Language; import org.apache.maven.api.PathScope; @@ -78,7 +76,6 @@ import org.apache.maven.api.services.MessageBuilderFactory; import org.apache.maven.api.services.ProjectManager; import org.apache.maven.api.services.ToolchainManager; - import static org.apache.maven.plugin.compiler.SourceDirectory.CLASS_FILE_SUFFIX; import static org.apache.maven.plugin.compiler.SourceDirectory.MODULE_INFO; @@ -294,7 +291,7 @@ final Charset charset() { * For security reasons, starting with Java 23 no annotation processing is done if neither * any {@code -processor}, {@code -processor path} or {@code -processor module} are set, or either {@code only} or {@code full} is set. * So literally the default is {@code none}. - * It is recommended to always provide the annotation processors you want to execute instead of using the {@code proc} configuration, to ensure that only desired processors are executed and not any "hidden" (and maybe malicious). + * It is recommended to always list the annotation processors you want to execute instead of using the {@code proc} configuration, to ensure that only desired processors are executed and not any "hidden" (and maybe malicious). * * @see #annotationProcessors * @see Inside Java 2024-06-18 Quality Heads up @@ -319,8 +316,11 @@ final Charset charset() { /** * Classpath elements to supply as annotation processor path. If specified, the compiler will detect annotation - * processors only in those classpath elements. If omitted, the default classpath is used to detect annotation + * processors only in those classpath elements. If omitted (and {@code proc} is set to {@code only} or {@code full}), the default classpath is used to detect annotation * processors. The detection itself depends on the configuration of {@link #annotationProcessors}. + * Since JDK 23 by default no annotation processing is performed as long as no processors is listed for security reasons. + * Therefore, you should always list the desired processors using this configuration element or {@code annotationProcessorPaths}. + * *

* Each classpath element is specified using their Maven coordinates (groupId, artifactId, version, classifier, * type). Transitive dependencies are added automatically. Exclusions are supported as well. Example: From d912b4ee0ef48ac6ddfe52cbd18ae2823d22a2a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Fri, 27 Jun 2025 23:05:01 +0200 Subject: [PATCH 3/9] Add documentation --- .../markdown/examples/annotationprocessor.md | 90 +++++++++++++++++++ src/site/site.xml | 1 + 2 files changed, 91 insertions(+) create mode 100644 src/site/markdown/examples/annotationprocessor.md diff --git a/src/site/markdown/examples/annotationprocessor.md b/src/site/markdown/examples/annotationprocessor.md new file mode 100644 index 000000000..c6d306c3c --- /dev/null +++ b/src/site/markdown/examples/annotationprocessor.md @@ -0,0 +1,90 @@ + + +# Annotation processors + +[Annotation processing](https://docs.oracle.com/en/java/javase/23/docs/specs/man/javac.html#annotation-processing) is used to let the compiler generate source code based on annotations. +For example, the [Hibernate Processor](https://hibernate.org/orm/processor/) provides an annotation processor to generate the JPA metamodel. + +## Recommended way to activate annotation processing +Up to JDK 23 the compiler automatically scanned the classpath for annotation processors and executed all found by default. +For security reasons this got disabled by default and annotation processing needs to be activated explicitly. +The recommended way for this is to list all desired processors using either the `` or the `` configuration. +Only those processors will get executed by the compiler. + +The following example shows, how to activate the Hibernate Processor. +```xml + + + [...] + + org.apache.maven.plugins + maven-compiler-plugin + ... + + + + org.hibernate.orm + hibernate-processor + {version.hibernate} + + + + + [...] + + +``` + +## Not recommended: Using the `proc` configuration + +If you don't want to provide a list of processors, you have to set the value of the `` configuration to either `only` or `full`. +The first will only scan the classpath for annotation processors and will execute them, while the later will also compile the code afterward. +Keep in mind that if no list of desired annotation processors is provided, using the `` configuration will execute found processors on the classpath. +**This might result in the execution of hidden and possible malicious processors.** +Therefor, using only the `proc` configuration is not recommended. + +You set the value of the `` configuration like every other [configuration](/usage.html) of the Maven Compiler Plugin: + +```xml + + + [...] + + org.apache.maven.plugins + maven-compiler-plugin + ... + + full + + + [...] + + +``` + +You can also just overwrite the default value of the property: + +```xml + + + full + + +``` \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index c7c1f721e..eceee30ae 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -40,6 +40,7 @@ under the License. + From 3ba10395fe6ffe3daf0106d4f6d5bc312f356a49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Sat, 28 Jun 2025 16:08:36 +0200 Subject: [PATCH 4/9] Fix typo --- .../org/apache/maven/plugin/compiler/AbstractCompilerMojo.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java index 0b2c27b81..e559e10e8 100644 --- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java +++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java @@ -286,7 +286,7 @@ final Charset charset() { * * * The default value depends on the JDK used for the build. - * Prior to Java 22, the default was {@code full}, rso annotation processing and compilation were executed without explicit configuration. + * Prior to Java 22, the default was {@code full}, so annotation processing and compilation were executed without explicit configuration. * * For security reasons, starting with Java 23 no annotation processing is done if neither * any {@code -processor}, {@code -processor path} or {@code -processor module} are set, or either {@code only} or {@code full} is set. From 45e2695741a19f7e1d1927f84150530a0c3d71a9 Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Sun, 29 Jun 2025 14:05:36 +0200 Subject: [PATCH 5/9] Revert the change of import order. Actually, this is done automatically when building the project. --- .../plugin/compiler/AbstractCompilerMojo.java | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java index e559e10e8..d2792ba6b 100644 --- a/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java +++ b/src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java @@ -18,6 +18,15 @@ */ package org.apache.maven.plugin.compiler; +import javax.lang.model.SourceVersion; +import javax.tools.DiagnosticListener; +import javax.tools.JavaCompiler; +import javax.tools.JavaFileManager; +import javax.tools.JavaFileObject; +import javax.tools.OptionChecker; +import javax.tools.Tool; +import javax.tools.ToolProvider; + import java.io.BufferedReader; import java.io.BufferedWriter; import java.io.File; @@ -42,14 +51,7 @@ import java.util.jar.JarFile; import java.util.jar.Manifest; import java.util.stream.Stream; -import javax.lang.model.SourceVersion; -import javax.tools.DiagnosticListener; -import javax.tools.JavaCompiler; -import javax.tools.JavaFileManager; -import javax.tools.JavaFileObject; -import javax.tools.OptionChecker; -import javax.tools.Tool; -import javax.tools.ToolProvider; + import org.apache.maven.api.JavaPathType; import org.apache.maven.api.Language; import org.apache.maven.api.PathScope; @@ -76,6 +78,7 @@ import org.apache.maven.api.services.MessageBuilderFactory; import org.apache.maven.api.services.ProjectManager; import org.apache.maven.api.services.ToolchainManager; + import static org.apache.maven.plugin.compiler.SourceDirectory.CLASS_FILE_SUFFIX; import static org.apache.maven.plugin.compiler.SourceDirectory.MODULE_INFO; From d212a26f944233a2a5a110e90cd4f288a733754f Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Sun, 29 Jun 2025 14:50:24 +0200 Subject: [PATCH 6/9] Change the example of annotation processor declaration for using the new dependency mechanism of Maven 4. Change indentation from 4 spaces to 2 spaces for consistency with other examples in APT files. --- .../markdown/examples/annotationprocessor.md | 92 ++++++++++--------- 1 file changed, 50 insertions(+), 42 deletions(-) diff --git a/src/site/markdown/examples/annotationprocessor.md b/src/site/markdown/examples/annotationprocessor.md index c6d306c3c..6fcc183dc 100644 --- a/src/site/markdown/examples/annotationprocessor.md +++ b/src/site/markdown/examples/annotationprocessor.md @@ -23,35 +23,38 @@ under the License. For example, the [Hibernate Processor](https://hibernate.org/orm/processor/) provides an annotation processor to generate the JPA metamodel. ## Recommended way to activate annotation processing -Up to JDK 23 the compiler automatically scanned the classpath for annotation processors and executed all found by default. -For security reasons this got disabled by default and annotation processing needs to be activated explicitly. -The recommended way for this is to list all desired processors using either the `` or the `` configuration. +Up to JDK 23, the compiler automatically scanned the classpath for annotation processors and executed all found by default. +For security reasons, this got disabled by default since JDK 23 and annotation processing needs to be activated explicitly. +The recommended way for this is to list all desired processors using either the `` plugin configuration +or by declaring the processors as dependencies of type `processor`. `classpath-processor` or `modular-processor`. Only those processors will get executed by the compiler. -The following example shows, how to activate the Hibernate Processor. +The following example shows how to activate the Hibernate Processor. +Note: this configuration requires Maven 4 with Maven Compiler Plugin 4. + ```xml - - - [...] - - org.apache.maven.plugins - maven-compiler-plugin - ... - - - - org.hibernate.orm - hibernate-processor - {version.hibernate} - - - - - [...] - - + + + [...] + + org.hibernate.orm + hibernate-processor + {version.hibernate} + processor + + [...] + + ``` +Like ordinary dependencies, processors can be placed on the processor class-path or processor module-path. +Each processor can be placed explicitly on one of those two kinds of path by specifying the +`classpath-processor` or `modular-processor` dependency type respectively. +If the specified type is only `processor`, then the Maven compiler plugin will try to guess on which path to place the processor. +Note that this guess is not guaranteed to be correct. +Developers are encouraged to declare a more explicit type when they know how the processor is intended to be used. + + ## Not recommended: Using the `proc` configuration If you don't want to provide a list of processors, you have to set the value of the `` configuration to either `only` or `full`. @@ -63,28 +66,33 @@ Therefor, using only the `proc` configuration is not recommended. You set the value of the `` configuration like every other [configuration](/usage.html) of the Maven Compiler Plugin: ```xml - + + [...] + - [...] - - org.apache.maven.plugins - maven-compiler-plugin - ... - - full - - - [...] + + org.apache.maven.plugins + maven-compiler-plugin + ${project.version} + + full + + + [...] - + [...] + + ``` You can also just overwrite the default value of the property: ```xml - - - full - - -``` \ No newline at end of file + + [...] + + full + + [...] + +``` From fbf5b51d2e591b67127ab9f36562a192d51f5f3d Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Sun, 29 Jun 2025 14:57:43 +0200 Subject: [PATCH 7/9] Add a dash in the filename for consistency with other pages. --- .../{annotationprocessor.md => annotation-processor.md} | 0 src/site/site.xml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename src/site/markdown/examples/{annotationprocessor.md => annotation-processor.md} (100%) diff --git a/src/site/markdown/examples/annotationprocessor.md b/src/site/markdown/examples/annotation-processor.md similarity index 100% rename from src/site/markdown/examples/annotationprocessor.md rename to src/site/markdown/examples/annotation-processor.md diff --git a/src/site/site.xml b/src/site/site.xml index eceee30ae..b6b054895 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -40,7 +40,7 @@ under the License. - + From fc9e8098aaa29fb02d71d6da04127661b6a3afe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Mon, 30 Jun 2025 17:14:19 +0200 Subject: [PATCH 8/9] Add Maven 3 and 4 section --- .../markdown/examples/annotation-processor.md | 46 ++++++++++++++++--- 1 file changed, 39 insertions(+), 7 deletions(-) diff --git a/src/site/markdown/examples/annotation-processor.md b/src/site/markdown/examples/annotation-processor.md index 6fcc183dc..5d1253feb 100644 --- a/src/site/markdown/examples/annotation-processor.md +++ b/src/site/markdown/examples/annotation-processor.md @@ -26,11 +26,41 @@ For example, the [Hibernate Processor](https://hibernate.org/orm/processor/) pro Up to JDK 23, the compiler automatically scanned the classpath for annotation processors and executed all found by default. For security reasons, this got disabled by default since JDK 23 and annotation processing needs to be activated explicitly. The recommended way for this is to list all desired processors using either the `` plugin configuration -or by declaring the processors as dependencies of type `processor`. `classpath-processor` or `modular-processor`. +or, when using Maven 4 and Maven Compiler Plugin version 4.x, by declaring the processors as dependencies of type `processor`. `classpath-processor` or `modular-processor`. Only those processors will get executed by the compiler. The following example shows how to activate the Hibernate Processor. -Note: this configuration requires Maven 4 with Maven Compiler Plugin 4. + +### Maven 3 +When using Maven 3 and Maven Compiler Plugin version 3.x you do this using the following configuration. + +```xml + + + [...] + + org.apache.maven.plugins + maven-compiler-plugin + ... + + + + org.hibernate.orm + hibernate-processor + ${version.hibernate} + + + + + [...] + + +``` + +### Maven 4 +Using Maven 4 and Maven Compiler Plugin 4.x, you can still use the same config as for Maven 3 and plugin version 3.x. +However, you can also make use of the new `processor` dependency type to shorten the configuration. +The following example shows this. ```xml @@ -39,7 +69,7 @@ Note: this configuration requires Maven 4 with Maven Compiler Plugin 4. org.hibernate.orm hibernate-processor - {version.hibernate} + ${version.hibernate} processor [...] @@ -52,16 +82,18 @@ Each processor can be placed explicitly on one of those two kinds of path by spe `classpath-processor` or `modular-processor` dependency type respectively. If the specified type is only `processor`, then the Maven compiler plugin will try to guess on which path to place the processor. Note that this guess is not guaranteed to be correct. -Developers are encouraged to declare a more explicit type when they know how the processor is intended to be used. +Developers are encouraged to declare a more explicit type (for example `classpath-processor`) when they know how the processor is intended to be used. ## Not recommended: Using the `proc` configuration +This section applies to Maven 3 and Maven 4. + If you don't want to provide a list of processors, you have to set the value of the `` configuration to either `only` or `full`. The first will only scan the classpath for annotation processors and will execute them, while the later will also compile the code afterward. Keep in mind that if no list of desired annotation processors is provided, using the `` configuration will execute found processors on the classpath. **This might result in the execution of hidden and possible malicious processors.** -Therefor, using only the `proc` configuration is not recommended. +Therefore, using only the `proc` configuration is not recommended. You set the value of the `` configuration like every other [configuration](/usage.html) of the Maven Compiler Plugin: @@ -73,7 +105,7 @@ You set the value of the `` configuration like every other [configuration] org.apache.maven.plugins maven-compiler-plugin - ${project.version} + ${version.maven-compiler-plugin} full @@ -94,5 +126,5 @@ You can also just overwrite the default value of the property: full [...] - + ``` From 6ee8c26d8707a5e1d9cb03cb107b0f83be273339 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20B=C3=BCnger?= Date: Mon, 30 Jun 2025 17:48:49 +0200 Subject: [PATCH 9/9] Feedback --- .../markdown/examples/annotation-processor.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/src/site/markdown/examples/annotation-processor.md b/src/site/markdown/examples/annotation-processor.md index 5d1253feb..efce889cf 100644 --- a/src/site/markdown/examples/annotation-processor.md +++ b/src/site/markdown/examples/annotation-processor.md @@ -35,31 +35,33 @@ The following example shows how to activate the Hibernate Processor. When using Maven 3 and Maven Compiler Plugin version 3.x you do this using the following configuration. ```xml - + + - [...] - - org.apache.maven.plugins - maven-compiler-plugin - ... - - - - org.hibernate.orm - hibernate-processor - ${version.hibernate} - - - - - [...] + [...] + + org.apache.maven.plugins + maven-compiler-plugin + ... + + + + org.hibernate.orm + hibernate-processor + ${version.hibernate} + + + + + [...] - + + ``` ### Maven 4 -Using Maven 4 and Maven Compiler Plugin 4.x, you can still use the same config as for Maven 3 and plugin version 3.x. -However, you can also make use of the new `processor` dependency type to shorten the configuration. +With Maven 4 and Maven Compiler Plugin 4.x the way described above got deprecated and will be removed in a future version of the plugin. +Configuration now makes use of the new `processor` dependency type to shorten the configuration. The following example shows this. ```xml