Java Doc for Processor.java in  » 6.0-JDK-Modules-sun » javac-compiler » javax » annotation » processing » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Annotation processing happens in a sequence of . On each round, a processor may be asked to a subset of the annotations found on the source and class files produced by a prior round. The inputs to the first round of processing are the initial inputs to a run of the tool; these initial inputs can be regarded as the output of a virtual zeroth round of processing. If a processor was asked to process on a given round, it will be asked to process on subsequent rounds, including the last round, even if there are no annotations for it to process. The tool infrastructure may also ask a processor to process files generated implicitly by the tool's operation.

Each implementation of a Processor must provide a public no-argument constructor to be used by tools to instantiate the processor. The tool infrastructure will interact with classes implementing this interface as follows:

1. If an existing Processor object is not being used, to create an instance of a processor the tool calls the no-arg constructor of the processor class.
2. Next, the tool calls the Processor.init init method with an appropriate ProcessingEnvironment .
3. Afterwards, the tool calls Processor.getSupportedAnnotationTypesgetSupportedAnnotationTypes , Processor.getSupportedOptionsgetSupportedOptions , and Processor.getSupportedSourceVersiongetSupportedSourceVersion . These methods are only called once per run, not on each round.
4. As appropriate, the tool calls the Processor.process process method on the Processor object; a new Processor object is not created for each round.

The tool uses a discovery process to find annotation processors and decide whether or not they should be run. By configuring the tool, the set of potential processors can be controlled. For example, for a javax.tools.JavaCompilerJavaCompiler the list of candidate processors to run can be or controlled by a used for a lookup. Other tool implementations may have different configuration mechanisms, such as command line options; for details, refer to the particular tool's documentation. Which processors the tool asks to is a function of what annotations are present on the , what , and whether or not a processor . A processor will be asked to process a subset of the annotation types it supports, possibly an empty set. For a given round, the tool computes the set of annotation types on the root elements. If there is at least one annotation type present, as processors claim annotation types, they are removed from the set of unmatched annotations. When the set is empty or no more processors are available, the round has run to completion. If there are no annotation types present, annotation processing still occurs but only universal processors which support processing "*" can claim the (empty) set of annotation types.

Note that if a processor supports "*" and returns true , all annotations are claimed. Therefore, a universal processor being used to, for example, implement additional validity checks should return false so as to not prevent other such checkers from being able to run.

If a processor throws an uncaught exception, the tool may cease other active annotation processors. If a processor raises an error, the current round will run to completion and the subsequent round will indicate an . Since annotation processors are run in a cooperative environment, a processor should throw an uncaught exception only in situations where no error recovery or reporting is feasible.

The tool environment is not required to support annotation processors that access environmental resources, either or , in a multi-threaded fashion.

If the methods that return configuration information about the annotation processor return null , return other invalid input, or throw an exception, the tool infrastructure must treat this as an error condition.

To be robust when running in different tool implementations, an annotation processor should have the following properties:

1. The result of processing a given input is not a function of the presence or absence of other inputs (orthogonality).
2. Processing the same input produces the same output (consistency).
3. Processing input A followed by processing input B is equivalent to processing B then A (commutativity)
4. Processing an input does not rely on the presence of the output of other annotation processors (independence)

The Filer interface discusses restrictions on how processors can operate on files.

Note that implementors of this interface may find it convenient to extend AbstractProcessor rather than implementing this interface directly.
author:
   Joseph D. Darcy
author:
   Scott Seligman
author:
   Peter von der Ahé
version:
   1.19 07/05/05
since:
   1.6

Since incomplete programs are being modeled, some of the parameters may only have partial information or may be null . At least one of element and userText must be non- null . If element is non- null , annotation and member may be null . Processors may not throw a NullPointerException if some parameters are null ; if a processor has no completions to offer based on the provided information, an empty iterable can be returned. The processor may also return a single completion with an empty value string and a message describing why there are no completions.

Completions are informative and may reflect additional validity checks performed by annotation processors. For example, consider the simple annotation:

 @MersennePrime {
 int value();
 }
 

 import static javax.annotation.processing.Completions.*;
 ...
 return Arrays.asList(
Completions.of(String) of ("3"),
 of("7"),
 of("31"),
 of("127"),
 of("8191"),
 of("131071"),
 of("524287"),
 of("2147483647"));
 

 return Arrays.asList(
Completions.of(StringString) of ("3",          "M2"),
 of("7",          "M3"),
 of("31",         "M5"),
 of("127",        "M7"),
 of("8191",       "M13"),
 of("131071",     "M17"),
 of("524287",     "M19"),
 of("2147483647", "M31"));
 

@MersennePrime(1

 return Arrays.asList(of("127",        "M7"),
 of("131071",     "M17"));
 

@MersennePrime(9

 return Collections.emptyList();
 

 return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
 

Each string returned in the set must be accepted by the following grammar:

SupportedAnnotationTypeString:

TypeName DotStar_opt

*

DotStar:

. *

Each string returned in the set must be a period separated sequence of :

SupportedOptionString:

Identifiers

Identifiers:

Identifier

Identifier . Identifiers

Identifier:

Syntactic identifier, including keywords and literals

A tool might use this information to determine if any options provided by a user are unrecognized by any processor, in which case it may wish to report a warning. the options recognized by this processor or an empty collection if none
See Also:   javax.annotation.processing.SupportedOptions

The input set will be empty if the processor supports "*" and the root elements have no annotations. A Processor must gracefully handle an empty set of annotations.
Parameters:
  annotations - the annotation types requested to be processed
Parameters:
  roundEnv - environment for information about the current and prior round whether or not the set of annotations are claimed by this processor