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 the types of the annotations {@linkplain AnnotatedConstruct present} + * on the {@linkplain + * RoundEnvironment#getRootElements root elements}, what {@linkplain + * #getSupportedAnnotationTypes annotation types a processor + * supports}, and whether or not a processor {@linkplain #process + * claims the annotation types 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 + * that are present on the elements enclosed within the root elements. + * If there is at least one annotation type present, then as + * processors claim annotation types, they are removed from the set of + * unmatched annotation types. 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 all annotation types, {@code "*"}, can claim the (empty) + * set of annotation types. + * + *
An annotation type is considered present if there is at least + * one annotation of that type present on an element enclosed within + * the root elements of a round. For this purpose, a type parameter is + * considered to be enclosed by its {@linkplain + * TypeParameterElement#getGenericElement generic + * element}. Annotations on {@linkplain + * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to + * annotations on elements, are ignored when computing whether or not + * an annotation type is present. + * + *
An annotation is present if it meets the definition of being + * present given in {@link AnnotatedConstruct}. In brief, an + * annotation is considered present for the purposes of discovery if + * it is directly present or present via inheritance. An annotation is + * not considered present by virtue of being wrapped by a + * container annotation. Operationally, this is equivalent to an + * annotation being present on an element if and only if it would be + * included in the results of {@link + * Elements#getAllAnnotationMirrors(Element)} called on that element. Since + * annotations inside container annotations are not considered + * present, to properly process {@linkplain + * java.lang.annotation.Repeatable repeatable annotation types}, + * processors are advised to include both the repeatable annotation + * type and its containing annotation type in the set of {@linkplain + * #getSupportedAnnotationTypes() supported annotation types} of a + * processor. + * + *
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. + * + * @author Joseph D. Darcy + * @author Scott Seligman + * @author Peter von der Ahé + * @since 1.6 + */ +public interface Processor { + /** + * Returns the options recognized by this processor. An + * implementation of the processing tool must provide a way to + * pass processor-specific options distinctly from options passed + * to the tool itself, see {@link ProcessingEnvironment#getOptions + * getOptions}. + * + *
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.
+ *
+ * @return the options recognized by this processor or an
+ * empty collection if none
+ * @see javax.annotation.processing.SupportedOptions
+ */
+ Set Each string returned in the set must be accepted by the
+ * following grammar:
+ *
+ * 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.
+ *
+ * @param annotations the annotation types requested to be processed
+ * @param roundEnv environment for information about the current and prior round
+ * @return whether or not the set of annotation types are claimed by this processor
+ */
+ boolean process(Set annotations,
+ RoundEnvironment roundEnv);
+
+ /**
+ * Returns to the tool infrastructure an iterable of suggested
+ * completions to an annotation. Since completions are being asked
+ * for, the information provided about the annotation may be
+ * incomplete, as if for a source code fragment. A processor may
+ * return an empty iterable. Annotation processors should focus
+ * their efforts on providing completions for annotation members
+ * with additional validity constraints known to the processor, for
+ * example an {@code int} member whose value should lie between 1
+ * and 10 or a string member that should be recognized by a known
+ * grammar, such as a regular expression or a URL.
+ *
+ * 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:
+ *
+ *
+ *
+ *
+ * where TypeName is as defined in
+ * The Java™ Language Specification.
+ *
+ * @return the names of the annotation types supported by this processor
+ * @see javax.annotation.processing.SupportedAnnotationTypes
+ * @jls 3.8 Identifiers
+ * @jls 6.5.5 Meaning of Type Names
+ */
+ Set
+ *
+ *
+ *
+ *
+ * (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 typed
+ *
+ *
+ * return 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"));
+ *
+ *
+ *
+ *
+ * the value of {@code userText} will be {@code "1"}; and only
+ * two of the primes are possible completions:
+ *
+ *
+ * @MersennePrime(1
+ *
+ *
+ *
+ *
+ * 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"));
+ *
+ *
+ *
+ *
+ * An appropriate response in this case is to either return an
+ * empty list of completions,
+ *
+ *
+ * @MersennePrime(9
+ *
+ *
+ *
+ *
+ * or a single empty completion with a helpful message
+ *
+ *
+ * return Collections.emptyList();
+ *
+ *
+ *
+ *
+ * @param element the element being annotated
+ * @param annotation the (perhaps partial) annotation being
+ * applied to the element
+ * @param member the annotation member to return possible completions for
+ * @param userText source code text to be completed
+ *
+ * @return suggested completions to the annotation
+ */
+ Iterable getCompletions(Element element,
+ AnnotationMirror annotation,
+ ExecutableElement member,
+ String userText);
+}
+ * return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
+ *
+ *