Proposal to change default annotation processing policy in JDK 23

[Joseph D. Darcy]

Hello,

This note is is to raise awareness of a forthcoming proposal to change 
the default annotation processing policy in javac in JDK 23*without* 
removing any annotation processing capabilities from javac.

     PR: https://github.com/openjdk/jdk/pull/19331
     CSR: https://bugs.openjdk.org/browse/JDK-8321319

In summary, with the proposed change, annotation processing will only be 
run with some explicit configuration of annotation processing or with an 
explicit request to run annotation processing on the javac command line. 
This would be a change in behavior from the existing default of looking 
to run annotation processing by searching the class path for processors 
_without_ any explicit annotation processing related options needing to 
be present.

Invocations of javac that rely on annotation processing without any 
explicit annotation processing configuration will need to be updated to 
keep running annotation processors. In JDK 21 and 22, javac prints a 
note identifying such invocations. To preserve the old behavior, 
"-proc:full" can be passed to javac. Support for "-proc:full" has been 
backported to several update release trains and is also supported as of 
a recent version of the Maven Compiler plugin. Additional details below.

----------------

Some background information, annotation processing is a compile-time 
facility added to the Java platform as a standard feature by JSR 269 in 
Java SE 6. In the JDK, standardized annotation processing is supported 
by javac; javac has three policies for combining compilation and 
annotation processing:

1) annotation processing followed by compilation
2) annotation processing alone *without* compilation
3) compilation *without* annotation processing

The second policy is requested using javac's "-proc:only" command line 
option and the third policy is requested using javac's "-proc:none" 
option. Starting in JDK 6, the first option was the default behavior in 
javac and the policy did not have an explicit name. JDK 21 added a 
"-proc:full" option to give a name to the historical default. Also, 
starting in JDK 21, javac prints a note if implicit usage of annotation 
processing under the default policy is detected; the note details 
various configuration options to avoid generation of the message. [1]

If this note is generated with JDK 21 or 22, the javac configuration 
will need to be updated to keep running annotation processors under the 
revised default policy.

As of the April 2024 JDK security updates, support for the "-proc:full" 
option has been backported to 17u (17.0.11) and 11u (11.0.23) for both 
Oracle JDK and OpenJDK distributions. [2] Additionally, Oracle's 8u 
release (8u411) also supports "-proc:full".

The old default behavior implicitly scans the class path looking for 
annotation processors that match annotations present in the set of 
source files being processed. Such processors are instantiated and code 
in those processors run in the context of the compiler. This policy of 
implicitly running annotation processors by default may have been 
reasonable when the feature was introduced in JDK 6 circa 2006, but from 
a current perspective, in the interest of making build output more 
robust against annotation processors unintentionally being placed on the 
class path, the policy should not be the default anymore.

The proposal is in JDK 23 to modify javac's default behavior to no 
longer implicitly look for annotation processors on the class path. To 
reiterate, the old class path searching behavior can be requested by 
including "-proc:full" when invoking javac or otherwise explicitly 
configuring the compilation for annotation processing. There are 
currently no plans to remove the "-proc:full" functionality.

This policy change was original made in an early-access JDK 22 build, 
but was later backed out due to larger than expected behavioral 
compatibility impacts. Since that time, "-proc:full" has been backported 
to earlier release trains and as of maven-compiler-plugin 3.13.0, the 
Maven Compiler plugin allows "-proc:full" as a compiler argument. [3] 
Thanks to the Maven maintainers for making this update.

With "-proc:full" backported, it is possible to configure a build that 
will work the same before and after the change in javac's default policy 
and run annotation processors out of the class path without any other 
options.

To summarize different scenarios and how they would be impacted by the 
policy change:

* compilation based on the class path, but *without* relying on implicit 
annotation processing: no effect from the policy change
* compilation explicitly configured for annotation processing 
(--processor-path, -processor, -proc:full etc.): no effect from the 
policy change
* compilation based on the class path that does rely on implicit 
annotation processing: annotation processors would not run under the new 
policy. Use "-proc:full" or otherwise configure annotation processing to 
keep running.

I'm aiming to have this change, JDK-8321314, implemented in JDK 23 
before ramp down 1.

Cheers,

-Joe

[1] The full text of the note is:

> Annotation processing is enabled because one or more processors were 
> found
> on the class path. A future release of javac may disable annotation 
> processing
> unless at least one processor is specified by name (-processor), or a 
> search
> path is specified (--processor-path, --processor-module-path), or 
> annotation
> processing is enabled explicitly (-proc:only, -proc:full).
> Use -Xlint:-options to suppress this message.
> Use -proc:none to disable annotation processing.

[2] See backport information in  JDK-8308245: "Add -proc:full to 
describe current default annotation processing policy":
https://bugs.openjdk.org/browse/JDK-8308245

[3] With the change, in Maven the property will appear as: "User 
Property: maven.compiler.proc" and therefore users may configure it via 
`-Dmaven.compiler.proc=full` on the command-line. For more information see:

https://issues.apache.org/jira/browse/MCOMPILER-548
https://www.mail-archive.com/dev@maven.apache.org/msg132181.html
https://maven.apache.org/plugins/maven-compiler-plugin/download.cgi

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20240523/c96da522/attachment-0001.htm>