| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Processor
The interface for an annotation processor.
Annotation processing happens in a sequence of {@linkplain javax.annotation.processing.RoundEnvironment rounds}. On each round, a processor may be asked to {@linkplain #process process} 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 {@code 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:
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 {@link javax.tools.JavaCompiler JavaCompiler} the list of candidate processors to run can be {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors set directly} or controlled by a {@linkplain javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path} used for a {@linkplain java.util.ServiceLoader service-style} 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 {@linkplain #process run} is a function of what annotations are present on the {@linkplain RoundEnvironment#getRootElements root elements}, what {@linkplain #getSupportedAnnotationTypes annotation types a processor processes}, and whether or not a processor {@linkplain #process claims the annotations it processes}. 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 {@code "*"} can claim the (empty) set of annotation types.
Note that if a processor supports {@code "*"} and returns {@code true}, all annotations are claimed. Therefore, a universal processor being used to, for example, implement additional validity checks should return {@code 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 {@linkplain RoundEnvironment#errorRaised error was raised}. 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 {@linkplain RoundEnvironment per round} or {@linkplain ProcessingEnvironment cross-round}, in a multi-threaded fashion.
If the methods that return configuration information about the annotation processor return {@code 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:
The {@link Filer} interface discusses restrictions on how processors can operate on files.
Note that implementors of this interface may find it convenient to extend {@link AbstractProcessor} rather than implementing this interface directly.
Method Summary | |
---|---|
Iterable |
getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText) Returns to the tool infrastructure an iterable of suggested completions to an annotation. |
Set |
Returns the names of the annotation types supported by this processor. |
Set |
Returns the options recognized by this processor. |
SourceVersion |
Returns the latest source version supported by this annotation processor. |
void |
init(ProcessingEnvironment processingEnv) Initializes the processor with the processing environment. |
boolean |
process(Set annotations, RoundEnvironment roundEnv) Processes a set of annotation types on type elements originating from the prior round and returns whether or not these annotations are claimed by this processor. |
Method Detail |
---|
public Iterable getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText)
Since incomplete programs are being modeled, some of the parameters may only have partial information or may be {@code null}. At least one of {@code element} and {@code userText} must be non-{@code null}. If {@code element} is non-{@code null}, {@code annotation} and {@code member} may be {@code null}. Processors may not throw a {@code NullPointerException} if some parameters are {@code 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:
(A Mersenne prime is prime number of the form 2n - 1.) Given an {@code AnnotationMirror} for this annotation type, a list of all such primes in the {@code int} range could be returned without examining any other arguments to {@code getCompletions}:@MersennePrime { int value(); }
A more informative set of completions would include the number of each prime:import static javax.annotation.processing.Completions.*; ... return Arrays.asList({@link Completions#of(String) of}("3"), of("7"), of("31"), of("127"), of("8191"), of("131071"), of("524287"), of("2147483647"));
However, if the {@code userText} is available, it can be checked to see if only a subset of the Mersenne primes are valid. For example, if the user has typedreturn Arrays.asList({@link Completions#of(String, String) 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
the value of {@code userText} will be {@code "1"}; and only
two of the primes are possible completions:
Sometimes no valid completion is possible. For example, there is no in-range Mersenne prime starting with 9:return Arrays.asList(of("127", "M7"), of("131071", "M17"));
@MersennePrime(9
An appropriate response in this case is to either return an
empty list of completions,
or a single empty completion with a helpful messagereturn Collections.emptyList();
return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
element
- the element being annotatedannotation
- the (perhaps partial) annotation being
applied to the elementmember
- the annotation member to return possible completions foruserText
- source code text to be completedpublic Set getSupportedAnnotationTypes()
Each string returned in the set must be accepted by the following grammar:
where TypeName is as defined in the Java Language Specification.
- SupportedAnnotationTypeString:
- TypeName DotStaropt
- *
- DotStar:
- . *
public Set getSupportedOptions()
Each string returned in the set must be a period separated sequence of {@linkplain javax.lang.model.SourceVersion#isIdentifier identifiers}:
- SupportedOptionString:
- Identifiers
- Identifiers:
- Identifier
- Identifier {@code .} 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.
public SourceVersion getSupportedSourceVersion()
public void init(ProcessingEnvironment processingEnv)
processingEnv
- environment for facilities the tool framework
provides to the processorpublic boolean process(Set annotations, RoundEnvironment roundEnv)
The input set will be empty if the processor supports {@code "*"} and the root elements have no annotations. A {@code Processor} must gracefully handle an empty set of annotations.
annotations
- the annotation types requested to be processedroundEnv
- environment for information about the current and prior round
| |||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |