Java Annotation Processor: Difference between revisions
(→TODO) |
|||
| Line 13: | Line 13: | ||
The processing API can only be used to generate new files, not change the existing ones. Lombok is an [[Lombok#Not_a_Typical_Use|exception]]. | The processing API can only be used to generate new files, not change the existing ones. Lombok is an [[Lombok#Not_a_Typical_Use|exception]]. | ||
=Annotation Processing Process= | |||
Unless annotation processing is disabled on <tt>javac</tt> with the <tt>-proc:none</tt> option, the compiler searches for any annotation processors that are available. The search path can be specified with the <tt>-processorpath</tt> option. If the option is not given, the user class path is used. Processors are located by means of service provider-configuration files named <tt>META-INF/services/javax.annotation.processing.Processor</tt> on the search path. Such files should contain the names of any annotation processors to be used, listed one per line. Alternatively, processors can be specified explicitly, using the <tt>-processor</tt> option. | |||
After scanning the source files and classes on the command line to determine what annotations are present, the compiler queries the processors to determine what annotations they process. When a match is found, the processor will be invoked. A processor may "claim" the annotations it processes, in which case no further attempt is made to find any processors for those annotations. Once all annotations have been claimed, the compiler does not look for additional processors. | |||
If any processors generate any new source files, another round of annotation processing will occur: any newly generated source files will be scanned, and the annotations processed as before. Any processors invoked on previous rounds will also be invoked on all subsequent rounds. This continues until no new source files are generated. | |||
After a round occurs where no new source files are generated, the annotation processors will be invoked one last time, to give them a chance to complete any work they may need to do. Finally, unless the <tt>-proc:only</tt> option is used, the compiler will compile the original and all the generated source files. | |||
=TODO= | =TODO= | ||
Revision as of 07:17, 1 November 2018
External
Internal
Overview
The Pluggable Annotation Processing API is specified by JSR 269 and can be used to develop custom annotation processors. Annotation processing is actively used in many Java libraries, for instance to generate metaclasses in JPA or to augment classes with boilerplate code in Lombok library.
The processing API can only be used to generate new files, not change the existing ones. Lombok is an exception.
Annotation Processing Process
Unless annotation processing is disabled on javac with the -proc:none option, the compiler searches for any annotation processors that are available. The search path can be specified with the -processorpath option. If the option is not given, the user class path is used. Processors are located by means of service provider-configuration files named META-INF/services/javax.annotation.processing.Processor on the search path. Such files should contain the names of any annotation processors to be used, listed one per line. Alternatively, processors can be specified explicitly, using the -processor option.
After scanning the source files and classes on the command line to determine what annotations are present, the compiler queries the processors to determine what annotations they process. When a match is found, the processor will be invoked. A processor may "claim" the annotations it processes, in which case no further attempt is made to find any processors for those annotations. Once all annotations have been claimed, the compiler does not look for additional processors.
If any processors generate any new source files, another round of annotation processing will occur: any newly generated source files will be scanned, and the annotations processed as before. Any processors invoked on previous rounds will also be invoked on all subsequent rounds. This continues until no new source files are generated.
After a round occurs where no new source files are generated, the annotation processors will be invoked one last time, to give them a chance to complete any work they may need to do. Finally, unless the -proc:only option is used, the compiler will compile the original and all the generated source files.
TODO
META-INF/services/javax.annotation.processing.Processor
http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javac.html#processing
API for processors: javax.annotation.processing, javax.lang.model.