1 /*
   2  * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.annotation.processing;
  27 
  28 import java.util.Set;
  29 import javax.lang.model.element.*;
  30 import javax.lang.model.SourceVersion;
  31 
  32 /**
  33  * The interface for an annotation processor.
  34  *
  35  * <p>Annotation processing happens in a sequence of {@linkplain
  36  * javax.annotation.processing.RoundEnvironment rounds}.  On each
  37  * round, a processor may be asked to {@linkplain #process process} a
  38  * subset of the annotations found on the source and class files
  39  * produced by a prior round.  The inputs to the first round of
  40  * processing are the initial inputs to a run of the tool; these
  41  * initial inputs can be regarded as the output of a virtual zeroth
  42  * round of processing.  If a processor was asked to process on a
  43  * given round, it will be asked to process on subsequent rounds,
  44  * including the last round, even if there are no annotations for it
  45  * to process.  The tool infrastructure may also ask a processor to
  46  * process files generated implicitly by the tool's operation.
  47  *
  48  * <p> Each implementation of a {@code Processor} must provide a
  49  * public no-argument constructor to be used by tools to instantiate
  50  * the processor.  The tool infrastructure will interact with classes
  51  * implementing this interface as follows:
  52  *
  53  * <ol>
  54  *
  55  * <li>If an existing {@code Processor} object is not being used, to
  56  * create an instance of a processor the tool calls the no-arg
  57  * constructor of the processor class.
  58  *
  59  * <li>Next, the tool calls the {@link #init init} method with
  60  * an appropriate {@code ProcessingEnvironment}.
  61  *
  62  * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes
  63  * getSupportedAnnotationTypes}, {@link #getSupportedOptions
  64  * getSupportedOptions}, and {@link #getSupportedSourceVersion
  65  * getSupportedSourceVersion}.  These methods are only called once per
  66  * run, not on each round.
  67  *
  68  * <li>As appropriate, the tool calls the {@link #process process}
  69  * method on the {@code Processor} object; a new {@code Processor}
  70  * object is <em>not</em> created for each round.
  71  *
  72  * </ol>
  73  *
  74  * If a processor object is created and used without the above
  75  * protocol being followed, then the processor's behavior is not
  76  * defined by this interface specification.
  77  *
  78  * <p> The tool uses a <i>discovery process</i> to find annotation
  79  * processors and decide whether or not they should be run.  By
  80  * configuring the tool, the set of potential processors can be
  81  * controlled.  For example, for a {@link javax.tools.JavaCompiler
  82  * JavaCompiler} the list of candidate processors to run can be
  83  * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
  84  * set directly} or controlled by a {@linkplain
  85  * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
  86  * used for a {@linkplain java.util.ServiceLoader service-style}
  87  * lookup.  Other tool implementations may have different
  88  * configuration mechanisms, such as command line options; for
  89  * details, refer to the particular tool's documentation.  Which
  90  * processors the tool asks to {@linkplain #process run} is a function
  91  * of what annotations are present on the {@linkplain
  92  * RoundEnvironment#getRootElements root elements}, what {@linkplain
  93  * #getSupportedAnnotationTypes annotation types a processor
  94  * processes}, and whether or not a processor {@linkplain #process
  95  * claims the annotations it processes}.  A processor will be asked to
  96  * process a subset of the annotation types it supports, possibly an
  97  * empty set.
  98  *
  99  * For a given round, the tool computes the set of annotation types on
 100  * the root elements.  If there is at least one annotation type
 101  * present, as processors claim annotation types, they are removed
 102  * from the set of unmatched annotations.  When the set is empty or no
 103  * more processors are available, the round has run to completion.  If
 104  * there are no annotation types present, annotation processing still
 105  * occurs but only <i>universal processors</i> which support
 106  * processing {@code "*"} can claim the (empty) set of annotation
 107  * types.
 108  *
 109  * <p>Note that if a processor supports {@code "*"} and returns {@code
 110  * true}, all annotations are claimed.  Therefore, a universal
 111  * processor being used to, for example, implement additional validity
 112  * checks should return {@code false} so as to not prevent other such
 113  * checkers from being able to run.
 114  *
 115  * <p>If a processor throws an uncaught exception, the tool may cease
 116  * other active annotation processors.  If a processor raises an
 117  * error, the current round will run to completion and the subsequent
 118  * round will indicate an {@linkplain RoundEnvironment#errorRaised
 119  * error was raised}.  Since annotation processors are run in a
 120  * cooperative environment, a processor should throw an uncaught
 121  * exception only in situations where no error recovery or reporting
 122  * is feasible.
 123  *
 124  * <p>The tool environment is not required to support annotation
 125  * processors that access environmental resources, either {@linkplain
 126  * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
 127  * cross-round}, in a multi-threaded fashion.
 128  *
 129  * <p>If the methods that return configuration information about the
 130  * annotation processor return {@code null}, return other invalid
 131  * input, or throw an exception, the tool infrastructure must treat
 132  * this as an error condition.
 133  *
 134  * <p>To be robust when running in different tool implementations, an
 135  * annotation processor should have the following properties:
 136  *
 137  * <ol>
 138  *
 139  * <li>The result of processing a given input is not a function of the presence or absence
 140  * of other inputs (orthogonality).
 141  *
 142  * <li>Processing the same input produces the same output (consistency).
 143  *
 144  * <li>Processing input <i>A</i> followed by processing input <i>B</i>
 145  * is equivalent to processing <i>B</i> then <i>A</i>
 146  * (commutativity)
 147  *
 148  * <li>Processing an input does not rely on the presence of the output
 149  * of other annotation processors (independence)
 150  *
 151  * </ol>
 152  *
 153  * <p>The {@link Filer} interface discusses restrictions on how
 154  * processors can operate on files.
 155  *
 156  * <p>Note that implementors of this interface may find it convenient
 157  * to extend {@link AbstractProcessor} rather than implementing this
 158  * interface directly.
 159  *
 160  * @author Joseph D. Darcy
 161  * @author Scott Seligman
 162  * @author Peter von der Ah&eacute;
 163  * @since 1.6
 164  */
 165 public interface Processor {
 166     /**
 167      * Returns the options recognized by this processor.  An
 168      * implementation of the processing tool must provide a way to
 169      * pass processor-specific options distinctly from options passed
 170      * to the tool itself, see {@link ProcessingEnvironment#getOptions
 171      * getOptions}.
 172      *
 173      * <p>Each string returned in the set must be a period separated
 174      * sequence of {@linkplain
 175      * javax.lang.model.SourceVersion#isIdentifier identifiers}:
 176      *
 177      * <blockquote>
 178      * <dl>
 179      * <dt><i>SupportedOptionString:</i>
 180      * <dd><i>Identifiers</i>
 181      * <p>
 182      * <dt><i>Identifiers:</i>
 183      * <dd> <i>Identifier</i>
 184      * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>
 185      * <p>
 186      * <dt><i>Identifier:</i>
 187      * <dd>Syntactic identifier, including keywords and literals
 188      * </dl>
 189      * </blockquote>
 190      *
 191      * <p> A tool might use this information to determine if any
 192      * options provided by a user are unrecognized by any processor,
 193      * in which case it may wish to report a warning.
 194      *
 195      * @return the options recognized by this processor or an
 196      *         empty collection if none
 197      * @see javax.annotation.processing.SupportedOptions
 198      */
 199     Set<String> getSupportedOptions();
 200 
 201     /**
 202      * Returns the names of the annotation types supported by this
 203      * processor.  An element of the result may be the canonical
 204      * (fully qualified) name of a supported annotation type.
 205      * Alternately it may be of the form &quot;<tt><i>name</i>.*</tt>&quot;
 206      * representing the set of all annotation types with canonical
 207      * names beginning with &quot;<tt><i>name.</i></tt>&quot;.  Finally, {@code
 208      * "*"} by itself represents the set of all annotation types,
 209      * including the empty set.  Note that a processor should not
 210      * claim {@code "*"} unless it is actually processing all files;
 211      * claiming unnecessary annotations may cause a performance
 212      * slowdown in some environments.
 213      *
 214      * <p>Each string returned in the set must be accepted by the
 215      * following grammar:
 216      *
 217      * <blockquote>
 218      * <dl>
 219      * <dt><i>SupportedAnnotationTypeString:</i>
 220      * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
 221      * <dd><tt>*</tt>
 222      * <p>
 223      * <dt><i>DotStar:</i>
 224      * <dd><tt>.</tt> <tt>*</tt>
 225      * </dl>
 226      * </blockquote>
 227      *
 228      * where <i>TypeName</i> is as defined in
 229      * <cite>The Java&trade; Language Specification</cite>.
 230      *
 231      * @return the names of the annotation types supported by this processor
 232      * @see javax.annotation.processing.SupportedAnnotationTypes
 233      * @jls 3.8 Identifiers
 234      * @jls 6.5.5 Meaning of Type Names
 235      */
 236     Set<String> getSupportedAnnotationTypes();
 237 
 238     /**
 239      * Returns the latest source version supported by this annotation
 240      * processor.
 241      *
 242      * @return the latest source version supported by this annotation
 243      * processor.
 244      * @see javax.annotation.processing.SupportedSourceVersion
 245      * @see ProcessingEnvironment#getSourceVersion
 246      */
 247     SourceVersion getSupportedSourceVersion();
 248 
 249     /**
 250      * Initializes the processor with the processing environment.
 251      *
 252      * @param processingEnv environment for facilities the tool framework
 253      * provides to the processor
 254      */
 255     void init(ProcessingEnvironment processingEnv);
 256 
 257     /**
 258      * Processes a set of annotation types on type elements
 259      * originating from the prior round and returns whether or not
 260      * these annotations are claimed by this processor.  If {@code
 261      * true} is returned, the annotations are claimed and subsequent
 262      * processors will not be asked to process them; if {@code false}
 263      * is returned, the annotations are unclaimed and subsequent
 264      * processors may be asked to process them.  A processor may
 265      * always return the same boolean value or may vary the result
 266      * based on chosen criteria.
 267      *
 268      * <p>The input set will be empty if the processor supports {@code
 269      * "*"} and the root elements have no annotations.  A {@code
 270      * Processor} must gracefully handle an empty set of annotations.
 271      *
 272      * @param annotations the annotation types requested to be processed
 273      * @param roundEnv  environment for information about the current and prior round
 274      * @return whether or not the set of annotations are claimed by this processor
 275      */
 276     boolean process(Set<? extends TypeElement> annotations,
 277                     RoundEnvironment roundEnv);
 278 
 279    /**
 280     * Returns to the tool infrastructure an iterable of suggested
 281     * completions to an annotation.  Since completions are being asked
 282     * for, the information provided about the annotation may be
 283     * incomplete, as if for a source code fragment. A processor may
 284     * return an empty iterable.  Annotation processors should focus
 285     * their efforts on providing completions for annotation members
 286     * with additional validity constraints known to the processor, for
 287     * example an {@code int} member whose value should lie between 1
 288     * and 10 or a string member that should be recognized by a known
 289     * grammar, such as a regular expression or a URL.
 290     *
 291     * <p>Since incomplete programs are being modeled, some of the
 292     * parameters may only have partial information or may be {@code
 293     * null}.  At least one of {@code element} and {@code userText}
 294     * must be non-{@code null}.  If {@code element} is non-{@code
 295     * null}, {@code annotation} and {@code member} may be {@code
 296     * null}.  Processors may not throw a {@code NullPointerException}
 297     * if some parameters are {@code null}; if a processor has no
 298     * completions to offer based on the provided information, an
 299     * empty iterable can be returned.  The processor may also return
 300     * a single completion with an empty value string and a message
 301     * describing why there are no completions.
 302     *
 303     * <p>Completions are informative and may reflect additional
 304     * validity checks performed by annotation processors.  For
 305     * example, consider the simple annotation:
 306     *
 307     * <blockquote>
 308     * <pre>
 309     * &#064;MersennePrime {
 310     *    int value();
 311     * }
 312     * </pre>
 313     * </blockquote>
 314     *
 315     * (A Mersenne prime is prime number of the form
 316     * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
 317     * for this annotation type, a list of all such primes in the
 318     * {@code int} range could be returned without examining any other
 319     * arguments to {@code getCompletions}:
 320     *
 321     * <blockquote>
 322     * <pre>
 323     * import static javax.annotation.processing.Completions.*;
 324     * ...
 325     * return Arrays.asList({@link Completions#of(String) of}(&quot;3&quot;),
 326     *                      of(&quot;7&quot;),
 327     *                      of(&quot;31&quot;),
 328     *                      of(&quot;127&quot;),
 329     *                      of(&quot;8191&quot;),
 330     *                      of(&quot;131071&quot;),
 331     *                      of(&quot;524287&quot;),
 332     *                      of(&quot;2147483647&quot;));
 333     * </pre>
 334     * </blockquote>
 335     *
 336     * A more informative set of completions would include the number
 337     * of each prime:
 338     *
 339     * <blockquote>
 340     * <pre>
 341     * return Arrays.asList({@link Completions#of(String, String) of}(&quot;3&quot;,          &quot;M2&quot;),
 342     *                      of(&quot;7&quot;,          &quot;M3&quot;),
 343     *                      of(&quot;31&quot;,         &quot;M5&quot;),
 344     *                      of(&quot;127&quot;,        &quot;M7&quot;),
 345     *                      of(&quot;8191&quot;,       &quot;M13&quot;),
 346     *                      of(&quot;131071&quot;,     &quot;M17&quot;),
 347     *                      of(&quot;524287&quot;,     &quot;M19&quot;),
 348     *                      of(&quot;2147483647&quot;, &quot;M31&quot;));
 349     * </pre>
 350     * </blockquote>
 351     *
 352     * However, if the {@code userText} is available, it can be checked
 353     * to see if only a subset of the Mersenne primes are valid.  For
 354     * example, if the user has typed
 355     *
 356     * <blockquote>
 357     * <code>
 358     * &#064;MersennePrime(1
 359     * </code>
 360     * </blockquote>
 361     *
 362     * the value of {@code userText} will be {@code "1"}; and only
 363     * two of the primes are possible completions:
 364     *
 365     * <blockquote>
 366     * <pre>
 367     * return Arrays.asList(of(&quot;127&quot;,        &quot;M7&quot;),
 368     *                      of(&quot;131071&quot;,     &quot;M17&quot;));
 369     * </pre>
 370     * </blockquote>
 371     *
 372     * Sometimes no valid completion is possible.  For example, there
 373     * is no in-range Mersenne prime starting with 9:
 374     *
 375     * <blockquote>
 376     * <code>
 377     * &#064;MersennePrime(9
 378     * </code>
 379     * </blockquote>
 380     *
 381     * An appropriate response in this case is to either return an
 382     * empty list of completions,
 383     *
 384     * <blockquote>
 385     * <pre>
 386     * return Collections.emptyList();
 387     * </pre>
 388     * </blockquote>
 389     *
 390     * or a single empty completion with a helpful message
 391     *
 392     * <blockquote>
 393     * <pre>
 394     * return Arrays.asList(of(&quot;&quot;, &quot;No in-range Mersenne primes start with 9&quot;));
 395     * </pre>
 396     * </blockquote>
 397     *
 398     * @param element the element being annotated
 399     * @param annotation the (perhaps partial) annotation being
 400     *                   applied to the element
 401     * @param member the annotation member to return possible completions for
 402     * @param userText source code text to be completed
 403     *
 404     * @return suggested completions to the annotation
 405     */
 406     Iterable<? extends Completion> getCompletions(Element element,
 407                                                   AnnotationMirror annotation,
 408                                                   ExecutableElement member,
 409                                                   String userText);
 410 }