Proposal to change default annotation processing policy in JDK 23

Thu May 30 19:51:25 UTC 2024

Hearing no objections here and after extensive discussion elsewhere 
online, I'll be pushing this change into JDK 23 shortly.

-Joe

On 5/23/2024 12:37 PM, Joseph D. Darcy wrote:
>
> 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/20240530/baa9314b/attachment-0001.htm>