Interface Processor

Method Detail

• getSupportedOptions

  Set<String> getSupportedOptions()

  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 getOptions.

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

  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.

  Returns:

  the options recognized by this processor or an empty collection if none

  See Also:

  SupportedOptions

• getSupportedAnnotationTypes

  Set<String> getSupportedAnnotationTypes()

  Returns the names of the annotation types supported by this processor. An element of the result may be the canonical (fully qualified) name of a supported annotation type. Alternately it may be of the form "name.*" representing the set of all annotation types with canonical names beginning with "name.". Finally, "*" by itself represents the set of all annotation types, including the empty set. Note that a processor should not claim "*" unless it is actually processing all files; claiming unnecessary annotations may cause a performance slowdown in some environments.

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

  SupportedAnnotationTypeString:

  TypeName DotStar_opt

  *

  DotStar:

  . *

  where TypeName is as defined in The Java™ Language Specification.

  Returns:

  the names of the annotation types supported by this processor

  See Also:

  SupportedAnnotationTypes

  See The Java™ Language Specification:

  3.8 Identifiers, 6.5.5 Meaning of Type Names

• getSupportedSourceVersion

  SourceVersion getSupportedSourceVersion()

  Returns the latest source version supported by this annotation processor.

  Returns:

  the latest source version supported by this annotation processor.

  See Also:

  SupportedSourceVersion, ProcessingEnvironment.getSourceVersion()

• init

  void init(ProcessingEnvironment processingEnv)

  Initializes the processor with the processing environment.

  Parameters:

  processingEnv - environment for facilities the tool framework provides to the processor

• process

  boolean process(Set<? extends TypeElement> 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. If true is returned, the annotations are claimed and subsequent processors will not be asked to process them; if false is returned, the annotations are unclaimed and subsequent processors may be asked to process them. A processor may always return the same boolean value or may vary the result based on chosen criteria.

  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

  roundEnv - environment for information about the current and prior round

  Returns:

  whether or not the set of annotations are claimed by this processor

• getCompletions

  Iterable<? extends Completion> getCompletions(Element element,
                                              AnnotationMirror annotation,
                                              ExecutableElement member,
                                              String userText)

  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 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 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();
   }
   

  (A Mersenne prime is prime number of the form 2ⁿ - 1.) Given an AnnotationMirror for this annotation type, a list of all such primes in the int range could be returned without examining any other arguments to getCompletions:

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

  A more informative set of completions would include the number of each prime:

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

  However, if the 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

  @MersennePrime(1

  the value of userText will be "1"; and only two of the primes are possible completions:

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

  Sometimes no valid completion is possible. For example, there is no in-range Mersenne prime starting with 9:

  @MersennePrime(9

  An appropriate response in this case is to either return an empty list of completions,

   return Collections.emptyList();
   

  or a single empty completion with a helpful message

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

  Parameters:

  element - the element being annotated

  annotation - the (perhaps partial) annotation being applied to the element

  member - the annotation member to return possible completions for

  userText - source code text to be completed

  Returns:

  suggested completions to the annotation