Mercurial > jdk8-mips64-public > langtools / file revision

 /*

  * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  *

  * This code is free software; you can redistribute it and/or modify it

  * under the terms of the GNU General Public License version 2 only, as

  * published by the Free Software Foundation.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle in the LICENSE file that accompanied this code.

  *

  * This code is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  * version 2 for more details (a copy is included in the LICENSE file that

  * accompanied this code).

  *

  * You should have received a copy of the GNU General Public License version

  * 2 along with this work; if not, write to the Free Software Foundation,

  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  *

  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.com if you need additional information or have any

  * questions.

  */

 package javax.annotation.processing;

 import java.util.Set;

 import javax.lang.model.util.Elements;

 import javax.lang.model.AnnotatedConstruct;

 import javax.lang.model.element.*;

 import javax.lang.model.SourceVersion;

 /**

  * The interface for an annotation processor.

  *

  * <p>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.

  *

  * <p> 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:

  *

  * <ol>

  *

  * <li>If an existing {@code Processor} object is not being used, to

  * create an instance of a processor the tool calls the no-arg

  * constructor of the processor class.

  *

  * <li>Next, the tool calls the {@link #init init} method with

  * an appropriate {@code ProcessingEnvironment}.

  *

  * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes

  * getSupportedAnnotationTypes}, {@link #getSupportedOptions

  * getSupportedOptions}, and {@link #getSupportedSourceVersion

  * getSupportedSourceVersion}.  These methods are only called once per

  * run, not on each round.

  *

  * <li>As appropriate, the tool calls the {@link #process process}

  * method on the {@code Processor} object; a new {@code Processor}

  * object is <em>not</em> created for each round.

  *

  * </ol>

  *

  * If a processor object is created and used without the above

  * protocol being followed, then the processor's behavior is not

  * defined by this interface specification.

  *

  * <p> The tool uses a <i>discovery process</i> 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 <em>{@linkplain AnnotatedConstruct present}</em>

  * 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 <i>universal processors</i> which support

  * processing all annotation types, {@code "*"}, can claim the (empty)

  * set of annotation types.

  *

  * <p>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.

  *

  * <p>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

  * <em>not</em> 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.

  *

  * <p>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.

  *

  * <p>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.

  *

  * <p>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.

  *

  * <p>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.

  *

  * <p>To be robust when running in different tool implementations, an

  * annotation processor should have the following properties:

  *

  * <ol>

  *

  * <li>The result of processing a given input is not a function of the presence or absence

  * of other inputs (orthogonality).

  *

  * <li>Processing the same input produces the same output (consistency).

  *

  * <li>Processing input <i>A</i> followed by processing input <i>B</i>

  * is equivalent to processing <i>B</i> then <i>A</i>

  * (commutativity)

  *

  * <li>Processing an input does not rely on the presence of the output

  * of other annotation processors (independence)

  *

  * </ol>

  *

  * <p>The {@link Filer} interface discusses restrictions on how

  * processors can operate on files.

  *

  * <p>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}.

      *

      * <p>Each string returned in the set must be a period separated

      * sequence of {@linkplain

      * javax.lang.model.SourceVersion#isIdentifier identifiers}:

      *

      * <blockquote>

      * <dl>

      * <dt><i>SupportedOptionString:</i>

      * <dd><i>Identifiers</i>

      *

      * <dt><i>Identifiers:</i>

      * <dd> <i>Identifier</i>

      * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>

      *

      * <dt><i>Identifier:</i>

      * <dd>Syntactic identifier, including keywords and literals

      * </dl>

      * </blockquote>

      *

      * <p> 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<String> getSupportedOptions();

     /**

      * 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 &quot;<tt><i>name</i>.*</tt>&quot;

      * representing the set of all annotation types with canonical

      * names beginning with &quot;<tt><i>name.</i></tt>&quot;.  Finally, {@code

      * "*"} by itself represents the set of all annotation types,

      * including the empty set.  Note that a processor should not

      * claim {@code "*"} unless it is actually processing all files;

      * claiming unnecessary annotations may cause a performance

      * slowdown in some environments.

      *

      * <p>Each string returned in the set must be accepted by the

      * following grammar:

      *

      * <blockquote>

      * <dl>

      * <dt><i>SupportedAnnotationTypeString:</i>

      * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>

      * <dd><tt>*</tt>

      *

      * <dt><i>DotStar:</i>

      * <dd><tt>.</tt> <tt>*</tt>

      * </dl>

      * </blockquote>

      *

      * where <i>TypeName</i> is as defined in

      * <cite>The Java&trade; Language Specification</cite>.

      *

      * @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<String> getSupportedAnnotationTypes();

     /**

      * Returns the latest source version supported by this annotation

      * processor.

      *

      * @return the latest source version supported by this annotation

      * processor.

      * @see javax.annotation.processing.SupportedSourceVersion

      * @see ProcessingEnvironment#getSourceVersion

      */

     SourceVersion getSupportedSourceVersion();

     /**

      * Initializes the processor with the processing environment.

      *

      * @param processingEnv environment for facilities the tool framework

      * provides to the processor

      */

     void init(ProcessingEnvironment processingEnv);

     /**

      * Processes a set of annotation types on type elements

      * originating from the prior round and returns whether or not

      * these annotation types are claimed by this processor.  If {@code

      * true} is returned, the annotation types are claimed and subsequent

      * processors will not be asked to process them; if {@code false}

      * is returned, the annotation types 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.

      *

      * <p>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<? extends TypeElement> 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.

     *

     * <p>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.

     *

     * <p>Completions are informative and may reflect additional

     * validity checks performed by annotation processors.  For

     * example, consider the simple annotation:

     *

     * <blockquote>

     * <pre>

     * @MersennePrime {

     *    int value();

     * }

     * </pre>

     * </blockquote>

     *

     * (A Mersenne prime is prime number of the form

     * 2<sup><i>n</i></sup> - 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}:

     *

     * <blockquote>

     * <pre>

     * 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"));

     * </pre>

     * </blockquote>

     *

     * A more informative set of completions would include the number

     * of each prime:

     *

     * <blockquote>

     * <pre>

     * 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"));

     * </pre>

     * </blockquote>

     *

     * 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

     *

     * <blockquote>

     * <code>

     * @MersennePrime(1

     * </code>

     * </blockquote>

     *

     * the value of {@code userText} will be {@code "1"}; and only

     * two of the primes are possible completions:

     *

     * <blockquote>

     * <pre>

     * return Arrays.asList(of("127",        "M7"),

     *                      of("131071",     "M17"));

     * </pre>

     * </blockquote>

     *

     * Sometimes no valid completion is possible.  For example, there

     * is no in-range Mersenne prime starting with 9:

     *

     * <blockquote>

     * <code>

     * @MersennePrime(9

     * </code>

     * </blockquote>

     *

     * An appropriate response in this case is to either return an

     * empty list of completions,

     *

     * <blockquote>

     * <pre>

     * return Collections.emptyList();

     * </pre>

     * </blockquote>

     *

     * or a single empty completion with a helpful message

     *

     * <blockquote>

     * <pre>

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

     * </pre>

     * </blockquote>

     *

     * @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<? extends Completion> getCompletions(Element element,

                                                   AnnotationMirror annotation,

                                                   ExecutableElement member,

                                                   String userText);

 }