This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-compiler-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new efc68bc Add JDK 23 information and example for annotation processing
(#939)
efc68bc is described below
commit efc68bcc8a5014762096d7ab75955ae821ff64fb
Author: Matthias Bünger <[email protected]>
AuthorDate: Mon Jun 30 18:18:29 2025 +0200
Add JDK 23 information and example for annotation processing (#939)
Contains two sections, one for Maven 3 and one for Maven 4.
---
.../plugin/compiler/AbstractCompilerMojo.java | 25 ++--
src/site/markdown/examples/annotation-processor.md | 132 +++++++++++++++++++++
src/site/site.xml | 1 +
3 files changed, 150 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 f935c8c..d2792ba 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 @@ public abstract class AbstractCompilerMojo implements
Mojo {
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:
* <ul>
- * <li>{@code none} – no annotation processing is performed.</li>
+ * <li>{@code none} – no annotation processing is performed, only
compilation is done.</li>
* <li>{@code only} – only annotation processing is done, no
compilation.</li>
- * <li>{@code full} – annotation processing and compilation are
done.</li>
+ * <li>{@code full} – annotation processing followed by compilation is
done.</li>
* </ul>
*
- * 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 <a href="https://inside.java/2024/06/18/quality-heads-up/";>Inside
Java 2024-06-18 Quality Heads up</a>
* @see <a
href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-proc";>javac
-proc</a>
* @see <a
href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#annotation-processing";>javac
Annotation Processing</a>
* @since 2.2
@@ -313,8 +319,11 @@ public abstract class AbstractCompilerMojo implements Mojo
{
/**
* 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}.
+ *
* <p>
* 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 0000000..efce889
--- /dev/null
+++ b/src/site/markdown/examples/annotation-processor.md
@@ -0,0 +1,132 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# 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 `<annotationProcessors>` 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
+<project>
+ <build>
+ <plugins>
+ [...]
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>...</version>
+ <configuration>
+ <annotationProcessorPaths>
+ <path>
+ <groupId>org.hibernate.orm</groupId>
+ <artifactId>hibernate-processor</artifactId>
+ <version>${version.hibernate}</version>
+ </path>
+ </annotationProcessorPaths>
+ </configuration>
+ </plugin>
+ [...]
+ </plugins>
+ </build>
+</project>
+```
+
+### 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
+<project>
+ <dependencies>
+ [...]
+ <dependency>
+ <groupId>org.hibernate.orm</groupId>
+ <artifactId>hibernate-processor</artifactId>
+ <version>${version.hibernate}</version>
+ <type>processor</type>
+ </dependency>
+ [...]
+ </dependencies>
+</project>
+```
+
+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
`<type>classpath-processor</type>`) 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 `<proc>` 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 `<proc>` 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 `<proc>` configuration like every other
[configuration](/usage.html) of the Maven Compiler Plugin:
+
+```xml
+<project>
+ [...]
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>${version.maven-compiler-plugin}</version>
+ <configuration>
+ <proc>full</proc>
+ </configuration>
+ </plugin>
+ [...]
+ </plugins>
+ [...]
+ </build>
+</project>
+```
+
+You can also just overwrite the default value of the property:
+
+```xml
+<project>
+ [...]
+ <properties>
+ <maven.compiler.proc>full</maven.compiler.proc>
+ </properties>
+ [...]
+</project>
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index c7c1f72..b6b0548 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -40,6 +40,7 @@ under the License.
<item name="Non-javac compilerIds" href="non-javac-compilers.html"/>
<item name="Older projects with module-info"
href="examples/module-info.html"/>
<item name="MultiRelease" href="multirelease.html"/>
+ <item name="Perform annotation processing"
href="examples/annotation-processor.html"/>
</menu>
</body>
</project>
