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