177  *
 178  * <ol>
 179  *
 180  * <li>The result of processing a given input is not a function of the presence or absence
 181  * of other inputs (orthogonality).
 182  *
 183  * <li>Processing the same input produces the same output (consistency).
 184  *
 185  * <li>Processing input <i>A</i> followed by processing input <i>B</i>
 186  * is equivalent to processing <i>B</i> then <i>A</i>
 187  * (commutativity)
 188  *
 189  * <li>Processing an input does not rely on the presence of the output
 190  * of other annotation processors (independence)
 191  *
 192  * </ol>
 193  *
 194  * <p>The {@link Filer} interface discusses restrictions on how
 195  * processors can operate on files.
 196  *
 197  * <p>Note that implementors of this interface may find it convenient
 198  * to extend {@link AbstractProcessor} rather than implementing this
 199  * interface directly.
 200  *
 201  * @author Joseph D. Darcy
 202  * @author Scott Seligman
 203  * @author Peter von der Ah&eacute;
 204  * @since 1.6
 205  */
 206 public interface Processor {
 207     /**
 208      * Returns the options recognized by this processor.  An
 209      * implementation of the processing tool must provide a way to
 210      * pass processor-specific options distinctly from options passed
 211      * to the tool itself, see {@link ProcessingEnvironment#getOptions
 212      * getOptions}.
 213      *
 214      * <p>Each string returned in the set must be a period separated
 215      * sequence of {@linkplain
 216      * javax.lang.model.SourceVersion#isIdentifier identifiers}:
 217      *

 298      */
 299     SourceVersion getSupportedSourceVersion();
 300 
 301     /**
 302      * Initializes the processor with the processing environment.
 303      *
 304      * @param processingEnv environment for facilities the tool framework
 305      * provides to the processor
 306      */
 307     void init(ProcessingEnvironment processingEnv);
 308 
 309     /**
 310      * Processes a set of annotation types on type elements
 311      * originating from the prior round and returns whether or not
 312      * these annotation types are claimed by this processor.  If {@code
 313      * true} is returned, the annotation types are claimed and subsequent
 314      * processors will not be asked to process them; if {@code false}
 315      * is returned, the annotation types are unclaimed and subsequent
 316      * processors may be asked to process them.  A processor may
 317      * always return the same boolean value or may vary the result
 318      * based on chosen criteria.
 319      *
 320      * <p>The input set will be empty if the processor supports {@code
 321      * "*"} and the root elements have no annotations.  A {@code
 322      * Processor} must gracefully handle an empty set of annotations.
 323      *
 324      * @param annotations the annotation types requested to be processed
 325      * @param roundEnv  environment for information about the current and prior round
 326      * @return whether or not the set of annotation types are claimed by this processor
 327      */
 328     boolean process(Set<? extends TypeElement> annotations,
 329                     RoundEnvironment roundEnv);
 330 
 331    /**
 332     * Returns to the tool infrastructure an iterable of suggested
 333     * completions to an annotation.  Since completions are being asked
 334     * for, the information provided about the annotation may be
 335     * incomplete, as if for a source code fragment. A processor may
 336     * return an empty iterable.  Annotation processors should focus
 337     * their efforts on providing completions for annotation members
 338     * with additional validity constraints known to the processor, for
 339     * example an {@code int} member whose value should lie between 1
 340     * and 10 or a string member that should be recognized by a known
 341     * grammar, such as a regular expression or a URL.
 342     *
 343     * <p>Since incomplete programs are being modeled, some of the
 344     * parameters may only have partial information or may be {@code
 345     * null}.  At least one of {@code element} and {@code userText}
 346     * must be non-{@code null}.  If {@code element} is non-{@code
 347     * null}, {@code annotation} and {@code member} may be {@code
 348     * null}.  Processors may not throw a {@code NullPointerException}
 349     * if some parameters are {@code null}; if a processor has no
 350     * completions to offer based on the provided information, an
 351     * empty iterable can be returned.  The processor may also return
 352     * a single completion with an empty value string and a message
 353     * describing why there are no completions.
 354     *
 355     * <p>Completions are informative and may reflect additional
 356     * validity checks performed by annotation processors.  For
 357     * example, consider the simple annotation:
 358     *
 359     * <blockquote>
 360     * <pre>
 361     * @MersennePrime {
 362     *    int value();
 363     * }
 364     * </pre>
 365     * </blockquote>
 366     *
 367     * (A Mersenne prime is prime number of the form

 177  *
 178  * <ol>
 179  *
 180  * <li>The result of processing a given input is not a function of the presence or absence
 181  * of other inputs (orthogonality).
 182  *
 183  * <li>Processing the same input produces the same output (consistency).
 184  *
 185  * <li>Processing input <i>A</i> followed by processing input <i>B</i>
 186  * is equivalent to processing <i>B</i> then <i>A</i>
 187  * (commutativity)
 188  *
 189  * <li>Processing an input does not rely on the presence of the output
 190  * of other annotation processors (independence)
 191  *
 192  * </ol>
 193  *
 194  * <p>The {@link Filer} interface discusses restrictions on how
 195  * processors can operate on files.
 196  *
 197  * @apiNote Implementors of this interface may find it convenient
 198  * to extend {@link AbstractProcessor} rather than implementing this
 199  * interface directly.
 200  *
 201  * @author Joseph D. Darcy
 202  * @author Scott Seligman
 203  * @author Peter von der Ah&eacute;
 204  * @since 1.6
 205  */
 206 public interface Processor {
 207     /**
 208      * Returns the options recognized by this processor.  An
 209      * implementation of the processing tool must provide a way to
 210      * pass processor-specific options distinctly from options passed
 211      * to the tool itself, see {@link ProcessingEnvironment#getOptions
 212      * getOptions}.
 213      *
 214      * <p>Each string returned in the set must be a period separated
 215      * sequence of {@linkplain
 216      * javax.lang.model.SourceVersion#isIdentifier identifiers}:
 217      *

 298      */
 299     SourceVersion getSupportedSourceVersion();
 300 
 301     /**
 302      * Initializes the processor with the processing environment.
 303      *
 304      * @param processingEnv environment for facilities the tool framework
 305      * provides to the processor
 306      */
 307     void init(ProcessingEnvironment processingEnv);
 308 
 309     /**
 310      * Processes a set of annotation types on type elements
 311      * originating from the prior round and returns whether or not
 312      * these annotation types are claimed by this processor.  If {@code
 313      * true} is returned, the annotation types are claimed and subsequent
 314      * processors will not be asked to process them; if {@code false}
 315      * is returned, the annotation types are unclaimed and subsequent
 316      * processors may be asked to process them.  A processor may
 317      * always return the same boolean value or may vary the result
 318      * based on its own chosen criteria.
 319      *
 320      * <p>The input set will be empty if the processor supports {@code
 321      * "*"} and the root elements have no annotations.  A {@code
 322      * Processor} must gracefully handle an empty set of annotations.
 323      *
 324      * @param annotations the annotation types requested to be processed
 325      * @param roundEnv  environment for information about the current and prior round
 326      * @return whether or not the set of annotation types are claimed by this processor
 327      */
 328     boolean process(Set<? extends TypeElement> annotations,
 329                     RoundEnvironment roundEnv);
 330 
 331    /**
 332     * Returns to the tool infrastructure an iterable of suggested
 333     * completions to an annotation.  Since completions are being asked
 334     * for, the information provided about the annotation may be
 335     * incomplete, as if for a source code fragment. A processor may
 336     * return an empty iterable.  Annotation processors should focus
 337     * their efforts on providing completions for annotation members
 338     * with additional validity constraints known to the processor, for
 339     * example an {@code int} member whose value should lie between 1
 340     * and 10 or a string member that should be recognized by a known
 341     * grammar, such as a regular expression or a URL.
 342     *
 343     * <p>Since incomplete programs are being modeled, some of the
 344     * parameters may only have partial information or may be {@code
 345     * null}.  At least one of {@code element} and {@code userText}
 346     * must be non-{@code null}.  If {@code element} is non-{@code null},
 347     * {@code annotation} and {@code member} may be {@code
 348     * null}.  Processors may not throw a {@code NullPointerException}
 349     * if some parameters are {@code null}; if a processor has no
 350     * completions to offer based on the provided information, an
 351     * empty iterable can be returned.  The processor may also return
 352     * a single completion with an empty value string and a message
 353     * describing why there are no completions.
 354     *
 355     * <p>Completions are informative and may reflect additional
 356     * validity checks performed by annotation processors.  For
 357     * example, consider the simple annotation:
 358     *
 359     * <blockquote>
 360     * <pre>
 361     * @MersennePrime {
 362     *    int value();
 363     * }
 364     * </pre>
 365     * </blockquote>
 366     *
 367     * (A Mersenne prime is prime number of the form