1 /*
2 * Copyright (c) 2005, 2017, 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.util.Elements;
30 import javax.lang.model.AnnotatedConstruct;
31 import javax.lang.model.element.*;
32 import javax.lang.model.SourceVersion;
33
34 /**
35 * The interface for an annotation processor.
36 *
37 * <p>Annotation processing happens in a sequence of {@linkplain
38 * javax.annotation.processing.RoundEnvironment rounds}. On each
39 * round, a processor may be asked to {@linkplain #process process} a
40 * subset of the annotations found on the source and class files
41 * produced by a prior round. The inputs to the first round of
42 * processing are the initial inputs to a run of the tool; these
43 * initial inputs can be regarded as the output of a virtual zeroth
44 * round of processing. If a processor was asked to process on a
45 * given round, it will be asked to process on subsequent rounds,
46 * including the last round, even if there are no annotations for it
47 * to process. The tool infrastructure may also ask a processor to
48 * process files generated implicitly by the tool's operation.
49 *
50 * <p> Each implementation of a {@code Processor} must provide a
51 * public no-argument constructor to be used by tools to instantiate
52 * the processor. The tool infrastructure will interact with classes
53 * implementing this interface as follows:
54 *
55 * <ol>
56 *
57 * <li>If an existing {@code Processor} object is not being used, to
58 * create an instance of a processor the tool calls the no-arg
59 * constructor of the processor class.
60 *
61 * <li>Next, the tool calls the {@link #init init} method with
62 * an appropriate {@code ProcessingEnvironment}.
63 *
64 * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes
65 * getSupportedAnnotationTypes}, {@link #getSupportedOptions
66 * getSupportedOptions}, and {@link #getSupportedSourceVersion
67 * getSupportedSourceVersion}. These methods are only called once per
68 * run, not on each round.
69 *
70 * <li>As appropriate, the tool calls the {@link #process process}
71 * method on the {@code Processor} object; a new {@code Processor}
72 * object is <em>not</em> created for each round.
73 *
74 * </ol>
75 *
76 * If a processor object is created and used without the above
77 * protocol being followed, then the processor's behavior is not
78 * defined by this interface specification.
79 *
80 * <p> The tool uses a <i>discovery process</i> to find annotation
81 * processors and decide whether or not they should be run. By
82 * configuring the tool, the set of potential processors can be
83 * controlled. For example, for a {@link javax.tools.JavaCompiler
84 * JavaCompiler} the list of candidate processors to run can be
85 * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
86 * set directly} or controlled by a {@linkplain
87 * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
88 * used for a {@linkplain java.util.ServiceLoader service-style}
89 * lookup. Other tool implementations may have different
90 * configuration mechanisms, such as command line options; for
91 * details, refer to the particular tool's documentation. Which
92 * processors the tool asks to {@linkplain #process run} is a function
93 * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em>
94 * on the {@linkplain
95 * RoundEnvironment#getRootElements root elements}, what {@linkplain
96 * #getSupportedAnnotationTypes annotation types a processor
97 * supports}, and whether or not a processor {@linkplain #process
98 * claims the annotation types it processes}. A processor will be asked to
99 * process a subset of the annotation types it supports, possibly an
100 * empty set.
101 *
102 * For a given round, the tool computes the set of annotation types
103 * that are present on the elements enclosed within the root elements.
104 * If there is at least one annotation type present, then as
105 * processors claim annotation types, they are removed from the set of
106 * unmatched annotation types. When the set is empty or no more
107 * processors are available, the round has run to completion. If
108 * there are no annotation types present, annotation processing still
109 * occurs but only <i>universal processors</i> which support
110 * processing all annotation types, {@code "*"}, can claim the (empty)
111 * set of annotation types.
112 *
113 * <p>An annotation type is considered present if there is at least
114 * one annotation of that type present on an element enclosed within
115 * the root elements of a round. For this purpose, a type parameter is
116 * considered to be enclosed by its {@linkplain
117 * TypeParameterElement#getGenericElement generic
118 * element}.
119
120 * For this purpose, a package element is <em>not</em> considered to
121 * enclose the top-level types within that package. (A root element
122 * representing a package is created when a {@code package-info} file
123 * is processed.) Likewise, for this purpose, a module element is
124 * <em>not</em> considered to enclose the packages within that
125 * module. (A root element representing a module is created when a
126 * {@code module-info} file is processed.)
127 *
128 * Annotations on {@linkplain
129 * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
130 * annotations on elements, are ignored when computing whether or not
131 * an annotation type is present.
132 *
133 * <p>An annotation is present if it meets the definition of being
134 * present given in {@link AnnotatedConstruct}. In brief, an
135 * annotation is considered present for the purposes of discovery if
136 * it is directly present or present via inheritance. An annotation is
137 * <em>not</em> considered present by virtue of being wrapped by a
138 * container annotation. Operationally, this is equivalent to an
139 * annotation being present on an element if and only if it would be
140 * included in the results of {@link
141 * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
142 * annotations inside container annotations are not considered
143 * present, to properly process {@linkplain
144 * java.lang.annotation.Repeatable repeatable annotation types},
145 * processors are advised to include both the repeatable annotation
146 * type and its containing annotation type in the set of {@linkplain
147 * #getSupportedAnnotationTypes() supported annotation types} of a
148 * processor.
149 *
150 * <p>Note that if a processor supports {@code "*"} and returns {@code
151 * true}, all annotations are claimed. Therefore, a universal
152 * processor being used to, for example, implement additional validity
153 * checks should return {@code false} so as to not prevent other such
154 * checkers from being able to run.
155 *
156 * <p>If a processor throws an uncaught exception, the tool may cease
157 * other active annotation processors. If a processor raises an
158 * error, the current round will run to completion and the subsequent
159 * round will indicate an {@linkplain RoundEnvironment#errorRaised
160 * error was raised}. Since annotation processors are run in a
161 * cooperative environment, a processor should throw an uncaught
162 * exception only in situations where no error recovery or reporting
163 * is feasible.
164 *
165 * <p>The tool environment is not required to support annotation
166 * processors that access environmental resources, either {@linkplain
167 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
168 * cross-round}, in a multi-threaded fashion.
169 *
170 * <p>If the methods that return configuration information about the
171 * annotation processor return {@code null}, return other invalid
172 * input, or throw an exception, the tool infrastructure must treat
173 * this as an error condition.
174 *
175 * <p>To be robust when running in different tool implementations, an
176 * annotation processor should have the following properties:
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é
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 *
218 * <blockquote>
219 * <dl>
220 * <dt><i>SupportedOptionString:</i>
221 * <dd><i>Identifiers</i>
222 *
223 * <dt><i>Identifiers:</i>
224 * <dd> <i>Identifier</i>
225 * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>
226 *
227 * <dt><i>Identifier:</i>
228 * <dd>Syntactic identifier, including keywords and literals
229 * </dl>
230 * </blockquote>
231 *
232 * <p> A tool might use this information to determine if any
233 * options provided by a user are unrecognized by any processor,
234 * in which case it may wish to report a warning.
235 *
236 * @return the options recognized by this processor or an
237 * empty collection if none
238 * @see javax.annotation.processing.SupportedOptions
239 */
240 Set<String> getSupportedOptions();
241
242 /**
243 * Returns the names of the annotation types supported by this
244 * processor. An element of the result may be the canonical
245 * (fully qualified) name of a supported annotation type.
246 * Alternately it may be of the form "<code><i>name</i>.*</code>"
247 * representing the set of all annotation types with canonical
248 * names beginning with "<code><i>name.</i></code>".
249 *
250 * In either of those cases, the name of the annotation type can
251 * be optionally preceded by a module name followed by a {@code
252 * "/"} character. For example, if a processor supports {@code
253 * "a.B"}, this can include multiple annotation types named {@code
254 * a.B} which reside in different modules. To only support {@code
255 * a.B} in the {@code Foo} module, instead use {@code "Foo/a.B"}.
256 *
257 * If a module name is included, only an annotation in that module
258 * is matched. In particular, if a module name is given in an
259 * environment where modules are not supported, such as an
260 * annotation processing environment configured for a {@linkplain
261 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
262 * source version} without modules, then the annotation types with
263 * a module name do <em>not</em> match.
264 *
265 * Finally, {@code "*"} by itself represents the set of all
266 * annotation types, including the empty set. Note that a
267 * processor should not claim {@code "*"} unless it is actually
268 * processing all files; claiming unnecessary annotations may
269 * cause a performance slowdown in some environments.
270 *
271 * <p>Each string returned in the set must be accepted by the
272 * following grammar:
273 *
274 * <blockquote>
275 * <dl>
276 * <dt><i>SupportedAnnotationTypeString:</i>
277 * <dd><i>ModulePrefix</i><sub><i>opt</i></sub> <i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
278 * <dd><code>*</code>
279 *
280 * <dt><i>ModulePrefix:</i>
281 * <dd><i>ModuleName</i> <code>/</code>
282 *
283 * <dt><i>DotStar:</i>
284 * <dd><code>.</code> <code>*</code>
285 * </dl>
286 * </blockquote>
287 *
288 * where <i>TypeName</i> and <i>ModuleName</i> are as defined in
289 * <cite>The Java™ Language Specification</cite>.
290 *
291 * @apiNote When running in an environment which supports modules,
292 * processors are encouraged to include the module prefix when
293 * describing their supported annotation types. The method {@link
294 * AbstractProcessor#getSupportedAnnotationTypes
295 * AbstractProcessor.getSupportedAnnotationTypes} provides support
296 * for stripping off the module prefix when running in an
297 * environment without modules.
298 *
299 * @return the names of the annotation types supported by this processor
300 * @see javax.annotation.processing.SupportedAnnotationTypes
301 * @jls 3.8 Identifiers
302 * @jls 6.5 Determining the Meaning of a Name
303 */
304 Set<String> getSupportedAnnotationTypes();
305
306 /**
307 * Returns the latest source version supported by this annotation
308 * processor.
309 *
310 * @return the latest source version supported by this annotation
311 * processor.
312 * @see javax.annotation.processing.SupportedSourceVersion
313 * @see ProcessingEnvironment#getSourceVersion
314 */
315 SourceVersion getSupportedSourceVersion();
316
317 /**
318 * Initializes the processor with the processing environment.
319 *
320 * @param processingEnv environment for facilities the tool framework
321 * provides to the processor
322 */
323 void init(ProcessingEnvironment processingEnv);
324
325 /**
326 * Processes a set of annotation types on type elements
327 * originating from the prior round and returns whether or not
328 * these annotation types are claimed by this processor. If {@code
329 * true} is returned, the annotation types are claimed and subsequent
330 * processors will not be asked to process them; if {@code false}
331 * is returned, the annotation types are unclaimed and subsequent
332 * processors may be asked to process them. A processor may
333 * always return the same boolean value or may vary the result
334 * based on its own chosen criteria.
335 *
336 * <p>The input set will be empty if the processor supports {@code
337 * "*"} and the root elements have no annotations. A {@code
338 * Processor} must gracefully handle an empty set of annotations.
339 *
340 * @param annotations the annotation types requested to be processed
341 * @param roundEnv environment for information about the current and prior round
342 * @return whether or not the set of annotation types are claimed by this processor
343 */
344 boolean process(Set<? extends TypeElement> annotations,
345 RoundEnvironment roundEnv);
346
347 /**
348 * Returns to the tool infrastructure an iterable of suggested
349 * completions to an annotation. Since completions are being asked
350 * for, the information provided about the annotation may be
351 * incomplete, as if for a source code fragment. A processor may
352 * return an empty iterable. Annotation processors should focus
353 * their efforts on providing completions for annotation members
354 * with additional validity constraints known to the processor, for
355 * example an {@code int} member whose value should lie between 1
356 * and 10 or a string member that should be recognized by a known
357 * grammar, such as a regular expression or a URL.
358 *
359 * <p>Since incomplete programs are being modeled, some of the
360 * parameters may only have partial information or may be {@code
361 * null}. At least one of {@code element} and {@code userText}
362 * must be non-{@code null}. If {@code element} is non-{@code null},
363 * {@code annotation} and {@code member} may be {@code
364 * null}. Processors may not throw a {@code NullPointerException}
365 * if some parameters are {@code null}; if a processor has no
366 * completions to offer based on the provided information, an
367 * empty iterable can be returned. The processor may also return
368 * a single completion with an empty value string and a message
369 * describing why there are no completions.
370 *
371 * <p>Completions are informative and may reflect additional
372 * validity checks performed by annotation processors. For
373 * example, consider the simple annotation:
374 *
375 * <blockquote>
376 * <pre>
377 * @MersennePrime {
378 * int value();
379 * }
380 * </pre>
381 * </blockquote>
382 *
383 * (A Mersenne prime is prime number of the form
384 * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
385 * for this annotation type, a list of all such primes in the
386 * {@code int} range could be returned without examining any other
387 * arguments to {@code getCompletions}:
388 *
389 * <blockquote>
390 * <pre>
391 * import static javax.annotation.processing.Completions.*;
392 * ...
393 * return Arrays.asList({@link Completions#of(String) of}("3"),
394 * of("7"),
395 * of("31"),
396 * of("127"),
397 * of("8191"),
398 * of("131071"),
399 * of("524287"),
400 * of("2147483647"));
401 * </pre>
402 * </blockquote>
403 *
404 * A more informative set of completions would include the number
405 * of each prime:
406 *
407 * <blockquote>
408 * <pre>
409 * return Arrays.asList({@link Completions#of(String, String) of}("3", "M2"),
410 * of("7", "M3"),
411 * of("31", "M5"),
412 * of("127", "M7"),
413 * of("8191", "M13"),
414 * of("131071", "M17"),
415 * of("524287", "M19"),
416 * of("2147483647", "M31"));
417 * </pre>
418 * </blockquote>
419 *
420 * However, if the {@code userText} is available, it can be checked
421 * to see if only a subset of the Mersenne primes are valid. For
422 * example, if the user has typed
423 *
424 * <blockquote>
425 * <code>
426 * @MersennePrime(1
427 * </code>
428 * </blockquote>
429 *
430 * the value of {@code userText} will be {@code "1"}; and only
431 * two of the primes are possible completions:
432 *
433 * <blockquote>
434 * <pre>
435 * return Arrays.asList(of("127", "M7"),
436 * of("131071", "M17"));
437 * </pre>
438 * </blockquote>
439 *
440 * Sometimes no valid completion is possible. For example, there
441 * is no in-range Mersenne prime starting with 9:
442 *
443 * <blockquote>
444 * <code>
445 * @MersennePrime(9
446 * </code>
447 * </blockquote>
448 *
449 * An appropriate response in this case is to either return an
450 * empty list of completions,
451 *
452 * <blockquote>
453 * <pre>
454 * return Collections.emptyList();
455 * </pre>
456 * </blockquote>
457 *
458 * or a single empty completion with a helpful message
459 *
460 * <blockquote>
461 * <pre>
462 * return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
463 * </pre>
464 * </blockquote>
465 *
466 * @param element the element being annotated
467 * @param annotation the (perhaps partial) annotation being
468 * applied to the element
469 * @param member the annotation member to return possible completions for
470 * @param userText source code text to be completed
471 *
472 * @return suggested completions to the annotation
473 */
474 Iterable<? extends Completion> getCompletions(Element element,
475 AnnotationMirror annotation,
476 ExecutableElement member,
477 String userText);
478 }