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
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 *
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
|
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.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
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 * processes}, 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 on
103 * the root elements. If there is at least one annotation type
104 * present, as processors claim annotation types, they are removed
105 * from the set of unmatched annotations. When the set is empty or no
106 * more processors are available, the round has run to completion. If
107 * there are no annotation types present, annotation processing still
108 * occurs but only <i>universal processors</i> which support
109 * processing {@code "*"} can claim the (empty) set of annotation
110 * types.
111 *
112 * <p>An annotation type is considered present if there is at least
113 * one annotation of that type present on an element enclosed within
114 * the root elements of a round. Annotations on {@linkplain
115 * ElementType#TYPE_USE type uses}, as opposed to annotations on
116 * elements, are <em>not</em> considered as part of the
117 * computation. For this purpose, a type parameter is considered to be
118 * enclosed by its {@linkplain TypeParameter#getGenericElement generic
119 * element}.
120 *
121 * <p>An annotation is present if it meets the definition of being
122 * present given in {@link AnnotatedConstruct}. In brief, an
123 * annotation is considered present for the purposes of discovery if
124 * it is directly present or present via inheritance. An annotation is
125 * <em>not</em> considered present by virtue of being wrapped by a
126 * container annotation. Operationally, this is equivalent to an
127 * annotation being present on an element if and only if it would be
128 * included in the results of {@link
129 * Elements#getAllAnnotationMirrors()} called on that element. Since
130 * annotations inside container annotations are not considered
131 * present, to properly process {@linkplain
132 * java.lang.annotation.Repeatable repeatable annotation types},
133 * processors are advised to include both the repeatable annotation
134 * type and its containing annotation type in the set of {@linkplain
135 * #getSupportedAnnotationTypes() supported annotation types} of a
136 * processor.
137 *
138 * <p>Note that if a processor supports {@code "*"} and returns {@code
139 * true}, all annotations are claimed. Therefore, a universal
140 * processor being used to, for example, implement additional validity
141 * checks should return {@code false} so as to not prevent other such
142 * checkers from being able to run.
143 *
144 * <p>If a processor throws an uncaught exception, the tool may cease
145 * other active annotation processors. If a processor raises an
146 * error, the current round will run to completion and the subsequent
147 * round will indicate an {@linkplain RoundEnvironment#errorRaised
148 * error was raised}. Since annotation processors are run in a
149 * cooperative environment, a processor should throw an uncaught
150 * exception only in situations where no error recovery or reporting
151 * is feasible.
152 *
153 * <p>The tool environment is not required to support annotation
154 * processors that access environmental resources, either {@linkplain
155 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment
156 * cross-round}, in a multi-threaded fashion.
157 *
269 * processor.
270 *
271 * @return the latest source version supported by this annotation
272 * processor.
273 * @see javax.annotation.processing.SupportedSourceVersion
274 * @see ProcessingEnvironment#getSourceVersion
275 */
276 SourceVersion getSupportedSourceVersion();
277
278 /**
279 * Initializes the processor with the processing environment.
280 *
281 * @param processingEnv environment for facilities the tool framework
282 * provides to the processor
283 */
284 void init(ProcessingEnvironment processingEnv);
285
286 /**
287 * Processes a set of annotation types on type elements
288 * originating from the prior round and returns whether or not
289 * these annotation types are claimed by this processor. If {@code
290 * true} is returned, the annotation types are claimed and subsequent
291 * processors will not be asked to process them; if {@code false}
292 * is returned, the annotation types are unclaimed and subsequent
293 * processors may be asked to process them. A processor may
294 * always return the same boolean value or may vary the result
295 * based on chosen criteria.
296 *
297 * <p>The input set will be empty if the processor supports {@code
298 * "*"} and the root elements have no annotations. A {@code
299 * Processor} must gracefully handle an empty set of annotations.
300 *
301 * @param annotations the annotation types requested to be processed
302 * @param roundEnv environment for information about the current and prior round
303 * @return whether or not the set of annotation types are claimed by this processor
304 */
305 boolean process(Set<? extends TypeElement> annotations,
306 RoundEnvironment roundEnv);
307
308 /**
309 * Returns to the tool infrastructure an iterable of suggested
310 * completions to an annotation. Since completions are being asked
311 * for, the information provided about the annotation may be
312 * incomplete, as if for a source code fragment. A processor may
313 * return an empty iterable. Annotation processors should focus
314 * their efforts on providing completions for annotation members
315 * with additional validity constraints known to the processor, for
316 * example an {@code int} member whose value should lie between 1
317 * and 10 or a string member that should be recognized by a known
318 * grammar, such as a regular expression or a URL.
319 *
320 * <p>Since incomplete programs are being modeled, some of the
321 * parameters may only have partial information or may be {@code
322 * null}. At least one of {@code element} and {@code userText}
323 * must be non-{@code null}. If {@code element} is non-{@code
|