declare namespace javax { namespace annotation { namespace processing { /** * 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 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 */ // @ts-ignore 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
*/
// @ts-ignore
getSupportedOptions(): Array 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
*/
// @ts-ignore
process(annotations: java.util.Set 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
*/
// @ts-ignore
getSupportedAnnotationTypes(): Array
*
*
*
* (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
*/
// @ts-ignore
getCompletions(element: javax.lang.model.element.Element, annotation: javax.lang.model.element.AnnotationMirror, member: javax.lang.model.element.ExecutableElement, userText: java.lang.String | string): java.lang.Iterable
* return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
*
*