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..d2792ba6b 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}, 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. + * So literally the default is {@code none}. + * 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 * @see javac -proc * @see javac Annotation Processing * @since 2.2 @@ -313,8 +319,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: diff --git a/src/site/markdown/examples/annotation-processor.md b/src/site/markdown/examples/annotation-processor.md new file mode 100644 index 000000000..efce889cf --- /dev/null +++ b/src/site/markdown/examples/annotation-processor.md @@ -0,0 +1,132 @@ + + +# 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 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, 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. + +### 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 +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 + + + [...] + + 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 (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.** +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: + +```xml + + [...] + + + + org.apache.maven.plugins + maven-compiler-plugin + ${version.maven-compiler-plugin} + + full + + + [...] + + [...] + + +``` + +You can also just overwrite the default value of the property: + +```xml + + [...] + + full + + [...] + +``` diff --git a/src/site/site.xml b/src/site/site.xml index c7c1f721e..b6b054895 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -40,6 +40,7 @@ under the License. +