1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/javax/annotation/processing/Processor.java Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,441 @@
1.4 +/*
1.5 + * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package javax.annotation.processing;
1.30 +
1.31 +import java.util.Set;
1.32 +import javax.lang.model.util.Elements;
1.33 +import javax.lang.model.AnnotatedConstruct;
1.34 +import javax.lang.model.element.*;
1.35 +import javax.lang.model.SourceVersion;
1.36 +
1.37 +/**
1.38 + * The interface for an annotation processor.
1.39 + *
1.40 + * <p>Annotation processing happens in a sequence of {@linkplain
1.41 + * javax.annotation.processing.RoundEnvironment rounds}. On each
1.42 + * round, a processor may be asked to {@linkplain #process process} a
1.43 + * subset of the annotations found on the source and class files
1.44 + * produced by a prior round. The inputs to the first round of
1.45 + * processing are the initial inputs to a run of the tool; these
1.46 + * initial inputs can be regarded as the output of a virtual zeroth
1.47 + * round of processing. If a processor was asked to process on a
1.48 + * given round, it will be asked to process on subsequent rounds,
1.49 + * including the last round, even if there are no annotations for it
1.50 + * to process. The tool infrastructure may also ask a processor to
1.51 + * process files generated implicitly by the tool's operation.
1.52 + *
1.53 + * <p> Each implementation of a {@code Processor} must provide a
1.54 + * public no-argument constructor to be used by tools to instantiate
1.55 + * the processor. The tool infrastructure will interact with classes
1.56 + * implementing this interface as follows:
1.57 + *
1.58 + * <ol>
1.59 + *
1.60 + * <li>If an existing {@code Processor} object is not being used, to
1.61 + * create an instance of a processor the tool calls the no-arg
1.62 + * constructor of the processor class.
1.63 + *
1.64 + * <li>Next, the tool calls the {@link #init init} method with
1.65 + * an appropriate {@code ProcessingEnvironment}.
1.66 + *
1.67 + * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes
1.68 + * getSupportedAnnotationTypes}, {@link #getSupportedOptions
1.69 + * getSupportedOptions}, and {@link #getSupportedSourceVersion
1.70 + * getSupportedSourceVersion}. These methods are only called once per
1.71 + * run, not on each round.
1.72 + *
1.73 + * <li>As appropriate, the tool calls the {@link #process process}
1.74 + * method on the {@code Processor} object; a new {@code Processor}
1.75 + * object is <em>not</em> created for each round.
1.76 + *
1.77 + * </ol>
1.78 + *
1.79 + * If a processor object is created and used without the above
1.80 + * protocol being followed, then the processor's behavior is not
1.81 + * defined by this interface specification.
1.82 + *
1.83 + * <p> The tool uses a <i>discovery process</i> to find annotation
1.84 + * processors and decide whether or not they should be run. By
1.85 + * configuring the tool, the set of potential processors can be
1.86 + * controlled. For example, for a {@link javax.tools.JavaCompiler
1.87 + * JavaCompiler} the list of candidate processors to run can be
1.88 + * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
1.89 + * set directly} or controlled by a {@linkplain
1.90 + * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
1.91 + * used for a {@linkplain java.util.ServiceLoader service-style}
1.92 + * lookup. Other tool implementations may have different
1.93 + * configuration mechanisms, such as command line options; for
1.94 + * details, refer to the particular tool's documentation. Which
1.95 + * processors the tool asks to {@linkplain #process run} is a function
1.96 + * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em>
1.97 + * on the {@linkplain
1.98 + * RoundEnvironment#getRootElements root elements}, what {@linkplain
1.99 + * #getSupportedAnnotationTypes annotation types a processor
1.100 + * supports}, and whether or not a processor {@linkplain #process
1.101 + * claims the annotation types it processes}. A processor will be asked to
1.102 + * process a subset of the annotation types it supports, possibly an
1.103 + * empty set.
1.104 + *
1.105 + * For a given round, the tool computes the set of annotation types
1.106 + * that are present on the elements enclosed within the root elements.
1.107 + * If there is at least one annotation type present, then as
1.108 + * processors claim annotation types, they are removed from the set of
1.109 + * unmatched annotation types. When the set is empty or no more
1.110 + * processors are available, the round has run to completion. If
1.111 + * there are no annotation types present, annotation processing still
1.112 + * occurs but only <i>universal processors</i> which support
1.113 + * processing all annotation types, {@code "*"}, can claim the (empty)
1.114 + * set of annotation types.
1.115 + *
1.116 + * <p>An annotation type is considered present if there is at least
1.117 + * one annotation of that type present on an element enclosed within
1.118 + * the root elements of a round. For this purpose, a type parameter is
1.119 + * considered to be enclosed by its {@linkplain
1.120 + * TypeParameterElement#getGenericElement generic
1.121 + * element}. Annotations on {@linkplain
1.122 + * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
1.123 + * annotations on elements, are ignored when computing whether or not
1.124 + * an annotation type is present.
1.125 + *
1.126 + * <p>An annotation is present if it meets the definition of being
1.127 + * present given in {@link AnnotatedConstruct}. In brief, an
1.128 + * annotation is considered present for the purposes of discovery if
1.129 + * it is directly present or present via inheritance. An annotation is
1.130 + * <em>not</em> considered present by virtue of being wrapped by a
1.131 + * container annotation. Operationally, this is equivalent to an
1.132 + * annotation being present on an element if and only if it would be
1.133 + * included in the results of {@link
1.134 + * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
1.135 + * annotations inside container annotations are not considered
1.136 + * present, to properly process {@linkplain
1.137 + * java.lang.annotation.Repeatable repeatable annotation types},
1.138 + * processors are advised to include both the repeatable annotation
1.139 + * type and its containing annotation type in the set of {@linkplain
1.140 + * #getSupportedAnnotationTypes() supported annotation types} of a
1.141 + * processor.
1.142 + *
1.143 + * <p>Note that if a processor supports {@code "*"} and returns {@code
1.144 + * true}, all annotations are claimed. Therefore, a universal
1.145 + * processor being used to, for example, implement additional validity
1.146 + * checks should return {@code false} so as to not prevent other such
1.147 + * checkers from being able to run.
1.148 + *
1.149 + * <p>If a processor throws an uncaught exception, the tool may cease
1.150 + * other active annotation processors. If a processor raises an
1.151 + * error, the current round will run to completion and the subsequent
1.152 + * round will indicate an {@linkplain RoundEnvironment#errorRaised
1.153 + * error was raised}. Since annotation processors are run in a
1.154 + * cooperative environment, a processor should throw an uncaught
1.155 + * exception only in situations where no error recovery or reporting
1.156 + * is feasible.
1.157 + *
1.158 + * <p>The tool environment is not required to support annotation
1.159 + * processors that access environmental resources, either {@linkplain
1.160 + * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
1.161 + * cross-round}, in a multi-threaded fashion.
1.162 + *
1.163 + * <p>If the methods that return configuration information about the
1.164 + * annotation processor return {@code null}, return other invalid
1.165 + * input, or throw an exception, the tool infrastructure must treat
1.166 + * this as an error condition.
1.167 + *
1.168 + * <p>To be robust when running in different tool implementations, an
1.169 + * annotation processor should have the following properties:
1.170 + *
1.171 + * <ol>
1.172 + *
1.173 + * <li>The result of processing a given input is not a function of the presence or absence
1.174 + * of other inputs (orthogonality).
1.175 + *
1.176 + * <li>Processing the same input produces the same output (consistency).
1.177 + *
1.178 + * <li>Processing input <i>A</i> followed by processing input <i>B</i>
1.179 + * is equivalent to processing <i>B</i> then <i>A</i>
1.180 + * (commutativity)
1.181 + *
1.182 + * <li>Processing an input does not rely on the presence of the output
1.183 + * of other annotation processors (independence)
1.184 + *
1.185 + * </ol>
1.186 + *
1.187 + * <p>The {@link Filer} interface discusses restrictions on how
1.188 + * processors can operate on files.
1.189 + *
1.190 + * <p>Note that implementors of this interface may find it convenient
1.191 + * to extend {@link AbstractProcessor} rather than implementing this
1.192 + * interface directly.
1.193 + *
1.194 + * @author Joseph D. Darcy
1.195 + * @author Scott Seligman
1.196 + * @author Peter von der Ahé
1.197 + * @since 1.6
1.198 + */
1.199 +public interface Processor {
1.200 + /**
1.201 + * Returns the options recognized by this processor. An
1.202 + * implementation of the processing tool must provide a way to
1.203 + * pass processor-specific options distinctly from options passed
1.204 + * to the tool itself, see {@link ProcessingEnvironment#getOptions
1.205 + * getOptions}.
1.206 + *
1.207 + * <p>Each string returned in the set must be a period separated
1.208 + * sequence of {@linkplain
1.209 + * javax.lang.model.SourceVersion#isIdentifier identifiers}:
1.210 + *
1.211 + * <blockquote>
1.212 + * <dl>
1.213 + * <dt><i>SupportedOptionString:</i>
1.214 + * <dd><i>Identifiers</i>
1.215 + *
1.216 + * <dt><i>Identifiers:</i>
1.217 + * <dd> <i>Identifier</i>
1.218 + * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>
1.219 + *
1.220 + * <dt><i>Identifier:</i>
1.221 + * <dd>Syntactic identifier, including keywords and literals
1.222 + * </dl>
1.223 + * </blockquote>
1.224 + *
1.225 + * <p> A tool might use this information to determine if any
1.226 + * options provided by a user are unrecognized by any processor,
1.227 + * in which case it may wish to report a warning.
1.228 + *
1.229 + * @return the options recognized by this processor or an
1.230 + * empty collection if none
1.231 + * @see javax.annotation.processing.SupportedOptions
1.232 + */
1.233 + Set<String> getSupportedOptions();
1.234 +
1.235 + /**
1.236 + * Returns the names of the annotation types supported by this
1.237 + * processor. An element of the result may be the canonical
1.238 + * (fully qualified) name of a supported annotation type.
1.239 + * Alternately it may be of the form "<tt><i>name</i>.*</tt>"
1.240 + * representing the set of all annotation types with canonical
1.241 + * names beginning with "<tt><i>name.</i></tt>". Finally, {@code
1.242 + * "*"} by itself represents the set of all annotation types,
1.243 + * including the empty set. Note that a processor should not
1.244 + * claim {@code "*"} unless it is actually processing all files;
1.245 + * claiming unnecessary annotations may cause a performance
1.246 + * slowdown in some environments.
1.247 + *
1.248 + * <p>Each string returned in the set must be accepted by the
1.249 + * following grammar:
1.250 + *
1.251 + * <blockquote>
1.252 + * <dl>
1.253 + * <dt><i>SupportedAnnotationTypeString:</i>
1.254 + * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
1.255 + * <dd><tt>*</tt>
1.256 + *
1.257 + * <dt><i>DotStar:</i>
1.258 + * <dd><tt>.</tt> <tt>*</tt>
1.259 + * </dl>
1.260 + * </blockquote>
1.261 + *
1.262 + * where <i>TypeName</i> is as defined in
1.263 + * <cite>The Java™ Language Specification</cite>.
1.264 + *
1.265 + * @return the names of the annotation types supported by this processor
1.266 + * @see javax.annotation.processing.SupportedAnnotationTypes
1.267 + * @jls 3.8 Identifiers
1.268 + * @jls 6.5.5 Meaning of Type Names
1.269 + */
1.270 + Set<String> getSupportedAnnotationTypes();
1.271 +
1.272 + /**
1.273 + * Returns the latest source version supported by this annotation
1.274 + * processor.
1.275 + *
1.276 + * @return the latest source version supported by this annotation
1.277 + * processor.
1.278 + * @see javax.annotation.processing.SupportedSourceVersion
1.279 + * @see ProcessingEnvironment#getSourceVersion
1.280 + */
1.281 + SourceVersion getSupportedSourceVersion();
1.282 +
1.283 + /**
1.284 + * Initializes the processor with the processing environment.
1.285 + *
1.286 + * @param processingEnv environment for facilities the tool framework
1.287 + * provides to the processor
1.288 + */
1.289 + void init(ProcessingEnvironment processingEnv);
1.290 +
1.291 + /**
1.292 + * Processes a set of annotation types on type elements
1.293 + * originating from the prior round and returns whether or not
1.294 + * these annotation types are claimed by this processor. If {@code
1.295 + * true} is returned, the annotation types are claimed and subsequent
1.296 + * processors will not be asked to process them; if {@code false}
1.297 + * is returned, the annotation types are unclaimed and subsequent
1.298 + * processors may be asked to process them. A processor may
1.299 + * always return the same boolean value or may vary the result
1.300 + * based on chosen criteria.
1.301 + *
1.302 + * <p>The input set will be empty if the processor supports {@code
1.303 + * "*"} and the root elements have no annotations. A {@code
1.304 + * Processor} must gracefully handle an empty set of annotations.
1.305 + *
1.306 + * @param annotations the annotation types requested to be processed
1.307 + * @param roundEnv environment for information about the current and prior round
1.308 + * @return whether or not the set of annotation types are claimed by this processor
1.309 + */
1.310 + boolean process(Set<? extends TypeElement> annotations,
1.311 + RoundEnvironment roundEnv);
1.312 +
1.313 + /**
1.314 + * Returns to the tool infrastructure an iterable of suggested
1.315 + * completions to an annotation. Since completions are being asked
1.316 + * for, the information provided about the annotation may be
1.317 + * incomplete, as if for a source code fragment. A processor may
1.318 + * return an empty iterable. Annotation processors should focus
1.319 + * their efforts on providing completions for annotation members
1.320 + * with additional validity constraints known to the processor, for
1.321 + * example an {@code int} member whose value should lie between 1
1.322 + * and 10 or a string member that should be recognized by a known
1.323 + * grammar, such as a regular expression or a URL.
1.324 + *
1.325 + * <p>Since incomplete programs are being modeled, some of the
1.326 + * parameters may only have partial information or may be {@code
1.327 + * null}. At least one of {@code element} and {@code userText}
1.328 + * must be non-{@code null}. If {@code element} is non-{@code
1.329 + * null}, {@code annotation} and {@code member} may be {@code
1.330 + * null}. Processors may not throw a {@code NullPointerException}
1.331 + * if some parameters are {@code null}; if a processor has no
1.332 + * completions to offer based on the provided information, an
1.333 + * empty iterable can be returned. The processor may also return
1.334 + * a single completion with an empty value string and a message
1.335 + * describing why there are no completions.
1.336 + *
1.337 + * <p>Completions are informative and may reflect additional
1.338 + * validity checks performed by annotation processors. For
1.339 + * example, consider the simple annotation:
1.340 + *
1.341 + * <blockquote>
1.342 + * <pre>
1.343 + * @MersennePrime {
1.344 + * int value();
1.345 + * }
1.346 + * </pre>
1.347 + * </blockquote>
1.348 + *
1.349 + * (A Mersenne prime is prime number of the form
1.350 + * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
1.351 + * for this annotation type, a list of all such primes in the
1.352 + * {@code int} range could be returned without examining any other
1.353 + * arguments to {@code getCompletions}:
1.354 + *
1.355 + * <blockquote>
1.356 + * <pre>
1.357 + * import static javax.annotation.processing.Completions.*;
1.358 + * ...
1.359 + * return Arrays.asList({@link Completions#of(String) of}("3"),
1.360 + * of("7"),
1.361 + * of("31"),
1.362 + * of("127"),
1.363 + * of("8191"),
1.364 + * of("131071"),
1.365 + * of("524287"),
1.366 + * of("2147483647"));
1.367 + * </pre>
1.368 + * </blockquote>
1.369 + *
1.370 + * A more informative set of completions would include the number
1.371 + * of each prime:
1.372 + *
1.373 + * <blockquote>
1.374 + * <pre>
1.375 + * return Arrays.asList({@link Completions#of(String, String) of}("3", "M2"),
1.376 + * of("7", "M3"),
1.377 + * of("31", "M5"),
1.378 + * of("127", "M7"),
1.379 + * of("8191", "M13"),
1.380 + * of("131071", "M17"),
1.381 + * of("524287", "M19"),
1.382 + * of("2147483647", "M31"));
1.383 + * </pre>
1.384 + * </blockquote>
1.385 + *
1.386 + * However, if the {@code userText} is available, it can be checked
1.387 + * to see if only a subset of the Mersenne primes are valid. For
1.388 + * example, if the user has typed
1.389 + *
1.390 + * <blockquote>
1.391 + * <code>
1.392 + * @MersennePrime(1
1.393 + * </code>
1.394 + * </blockquote>
1.395 + *
1.396 + * the value of {@code userText} will be {@code "1"}; and only
1.397 + * two of the primes are possible completions:
1.398 + *
1.399 + * <blockquote>
1.400 + * <pre>
1.401 + * return Arrays.asList(of("127", "M7"),
1.402 + * of("131071", "M17"));
1.403 + * </pre>
1.404 + * </blockquote>
1.405 + *
1.406 + * Sometimes no valid completion is possible. For example, there
1.407 + * is no in-range Mersenne prime starting with 9:
1.408 + *
1.409 + * <blockquote>
1.410 + * <code>
1.411 + * @MersennePrime(9
1.412 + * </code>
1.413 + * </blockquote>
1.414 + *
1.415 + * An appropriate response in this case is to either return an
1.416 + * empty list of completions,
1.417 + *
1.418 + * <blockquote>
1.419 + * <pre>
1.420 + * return Collections.emptyList();
1.421 + * </pre>
1.422 + * </blockquote>
1.423 + *
1.424 + * or a single empty completion with a helpful message
1.425 + *
1.426 + * <blockquote>
1.427 + * <pre>
1.428 + * return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
1.429 + * </pre>
1.430 + * </blockquote>
1.431 + *
1.432 + * @param element the element being annotated
1.433 + * @param annotation the (perhaps partial) annotation being
1.434 + * applied to the element
1.435 + * @param member the annotation member to return possible completions for
1.436 + * @param userText source code text to be completed
1.437 + *
1.438 + * @return suggested completions to the annotation
1.439 + */
1.440 + Iterable<? extends Completion> getCompletions(Element element,
1.441 + AnnotationMirror annotation,
1.442 + ExecutableElement member,
1.443 + String userText);
1.444 +}
