001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.annotation.processing;
027
028 import java.util.Set;
029 import javax.lang.model.element.*;
030 import javax.lang.model.SourceVersion;
031
032 /**
033 * The interface for an annotation processor.
034 *
035 * <p>Annotation processing happens in a sequence of {@linkplain
036 * javax.annotation.processing.RoundEnvironment rounds}. On each
037 * round, a processor may be asked to {@linkplain #process process} a
038 * subset of the annotations found on the source and class files
039 * produced by a prior round. The inputs to the first round of
040 * processing are the initial inputs to a run of the tool; these
041 * initial inputs can be regarded as the output of a virtual zeroth
042 * round of processing. If a processor was asked to process on a
043 * given round, it will be asked to process on subsequent rounds,
044 * including the last round, even if there are no annotations for it
045 * to process. The tool infrastructure may also ask a processor to
046 * process files generated implicitly by the tool's operation.
047 *
048 * <p> Each implementation of a {@code Processor} must provide a
049 * public no-argument constructor to be used by tools to instantiate
050 * the processor. The tool infrastructure will interact with classes
051 * implementing this interface as follows:
052 *
053 * <ol>
054 *
055 * <li>If an existing {@code Processor} object is not being used, to
056 * create an instance of a processor the tool calls the no-arg
057 * constructor of the processor class.
058 *
059 * <li>Next, the tool calls the {@link #init init} method with
060 * an appropriate {@code ProcessingEnvironment}.
061 *
062 * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes
063 * getSupportedAnnotationTypes}, {@link #getSupportedOptions
064 * getSupportedOptions}, and {@link #getSupportedSourceVersion
065 * getSupportedSourceVersion}. These methods are only called once per
066 * run, not on each round.
067 *
068 * <li>As appropriate, the tool calls the {@link #process process}
069 * method on the {@code Processor} object; a new {@code Processor}
070 * object is <em>not</em> created for each round.
071 *
072 * </ol>
073 *
074 * If a processor object is created and used without the above
075 * protocol being followed, then the processor's behavior is not
076 * defined by this interface specification.
077 *
078 * <p> The tool uses a <i>discovery process</i> to find annotation
079 * processors and decide whether or not they should be run. By
080 * configuring the tool, the set of potential processors can be
081 * controlled. For example, for a {@link javax.tools.JavaCompiler
082 * JavaCompiler} the list of candidate processors to run can be
083 * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors
084 * set directly} or controlled by a {@linkplain
085 * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path}
086 * used for a {@linkplain java.util.ServiceLoader service-style}
087 * lookup. Other tool implementations may have different
088 * configuration mechanisms, such as command line options; for
089 * details, refer to the particular tool's documentation. Which
090 * processors the tool asks to {@linkplain #process run} is a function
091 * of what annotations are present on the {@linkplain
092 * RoundEnvironment#getRootElements root elements}, what {@linkplain
093 * #getSupportedAnnotationTypes annotation types a processor
094 * processes}, and whether or not a processor {@linkplain #process
095 * claims the annotations it processes}. A processor will be asked to
096 * process a subset of the annotation types it supports, possibly an
097 * empty set.
098 *
099 * 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 *
129 * <p>If the methods that return configuration information about the
130 * annotation processor return {@code null}, return other invalid
131 * input, or throw an exception, the tool infrastructure must treat
132 * this as an error condition.
133 *
134 * <p>To be robust when running in different tool implementations, an
135 * annotation processor should have the following properties:
136 *
137 * <ol>
138 *
139 * <li>The result of processing a given input is not a function of the presence or absence
140 * of other inputs (orthogonality).
141 *
142 * <li>Processing the same input produces the same output (consistency).
143 *
144 * <li>Processing input <i>A</i> followed by processing input <i>B</i>
145 * is equivalent to processing <i>B</i> then <i>A</i>
146 * (commutativity)
147 *
148 * <li>Processing an input does not rely on the presence of the output
149 * of other annotation processors (independence)
150 *
151 * </ol>
152 *
153 * <p>The {@link Filer} interface discusses restrictions on how
154 * processors can operate on files.
155 *
156 * <p>Note that implementors of this interface may find it convenient
157 * to extend {@link AbstractProcessor} rather than implementing this
158 * interface directly.
159 *
160 * @author Joseph D. Darcy
161 * @author Scott Seligman
162 * @author Peter von der Ahé
163 * @since 1.6
164 */
165 public interface Processor {
166 /**
167 * Returns the options recognized by this processor. An
168 * implementation of the processing tool must provide a way to
169 * pass processor-specific options distinctly from options passed
170 * to the tool itself, see {@link ProcessingEnvironment#getOptions
171 * getOptions}.
172 *
173 * <p>Each string returned in the set must be a period separated
174 * sequence of {@linkplain
175 * javax.lang.model.SourceVersion#isIdentifier identifiers}:
176 *
177 * <blockquote>
178 * <dl>
179 * <dt><i>SupportedOptionString:</i>
180 * <dd><i>Identifiers</i>
181 * <p>
182 * <dt><i>Identifiers:</i>
183 * <dd> <i>Identifier</i>
184 * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>
185 * <p>
186 * <dt><i>Identifier:</i>
187 * <dd>Syntactic identifier, including keywords and literals
188 * </dl>
189 * </blockquote>
190 *
191 * <p> A tool might use this information to determine if any
192 * options provided by a user are unrecognized by any processor,
193 * in which case it may wish to report a warning.
194 *
195 * @return the options recognized by this processor or an
196 * empty collection if none
197 * @see javax.annotation.processing.SupportedOptions
198 */
199 Set<String> getSupportedOptions();
200
201 /**
202 * Returns the names of the annotation types supported by this
203 * processor. An element of the result may be the canonical
204 * (fully qualified) name of a supported annotation type.
205 * Alternately it may be of the form "<tt><i>name</i>.*</tt>"
206 * representing the set of all annotation types with canonical
207 * names beginning with "<tt><i>name.</i></tt>". Finally, {@code
208 * "*"} by itself represents the set of all annotation types,
209 * including the empty set. Note that a processor should not
210 * claim {@code "*"} unless it is actually processing all files;
211 * claiming unnecessary annotations may cause a performance
212 * slowdown in some environments.
213 *
214 * <p>Each string returned in the set must be accepted by the
215 * following grammar:
216 *
217 * <blockquote>
218 * <dl>
219 * <dt><i>SupportedAnnotationTypeString:</i>
220 * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
221 * <dd><tt>*</tt>
222 * <p>
223 * <dt><i>DotStar:</i>
224 * <dd><tt>.</tt> <tt>*</tt>
225 * </dl>
226 * </blockquote>
227 *
228 * where <i>TypeName</i> is as defined in the <i>Java Language Specification</i>.
229 *
230 * @return the names of the annotation types supported by this processor
231 * @see javax.annotation.processing.SupportedAnnotationTypes
232 * @jls3 3.8 Identifiers
233 * @jls3 6.5.5 Meaning of Type Names
234 */
235 Set<String> getSupportedAnnotationTypes();
236
237 /**
238 * Returns the latest source version supported by this annotation
239 * processor.
240 *
241 * @return the latest source version supported by this annotation
242 * processor.
243 * @see javax.annotation.processing.SupportedSourceVersion
244 * @see ProcessingEnvironment#getSourceVersion
245 */
246 SourceVersion getSupportedSourceVersion();
247
248 /**
249 * Initializes the processor with the processing environment.
250 *
251 * @param processingEnv environment for facilities the tool framework
252 * provides to the processor
253 */
254 void init(ProcessingEnvironment processingEnv);
255
256 /**
257 * Processes a set of annotation types on type elements
258 * originating from the prior round and returns whether or not
259 * these annotations are claimed by this processor. If {@code
260 * true} is returned, the annotations are claimed and subsequent
261 * processors will not be asked to process them; if {@code false}
262 * is returned, the annotations are unclaimed and subsequent
263 * processors may be asked to process them. A processor may
264 * always return the same boolean value or may vary the result
265 * based on chosen criteria.
266 *
267 * <p>The input set will be empty if the processor supports {@code
268 * "*"} and the root elements have no annotations. A {@code
269 * Processor} must gracefully handle an empty set of annotations.
270 *
271 * @param annotations the annotation types requested to be processed
272 * @param roundEnv environment for information about the current and prior round
273 * @return whether or not the set of annotations are claimed by this processor
274 */
275 boolean process(Set<? extends TypeElement> annotations,
276 RoundEnvironment roundEnv);
277
278 /**
279 * Returns to the tool infrastructure an iterable of suggested
280 * completions to an annotation. Since completions are being asked
281 * for, the information provided about the annotation may be
282 * incomplete, as if for a source code fragment. A processor may
283 * return an empty iterable. Annotation processors should focus
284 * their efforts on providing completions for annotation members
285 * with additional validity constraints known to the processor, for
286 * example an {@code int} member whose value should lie between 1
287 * and 10 or a string member that should be recognized by a known
288 * grammar, such as a regular expression or a URL.
289 *
290 * <p>Since incomplete programs are being modeled, some of the
291 * parameters may only have partial information or may be {@code
292 * null}. At least one of {@code element} and {@code userText}
293 * must be non-{@code null}. If {@code element} is non-{@code
294 * null}, {@code annotation} and {@code member} may be {@code
295 * null}. Processors may not throw a {@code NullPointerException}
296 * if some parameters are {@code null}; if a processor has no
297 * completions to offer based on the provided information, an
298 * empty iterable can be returned. The processor may also return
299 * a single completion with an empty value string and a message
300 * describing why there are no completions.
301 *
302 * <p>Completions are informative and may reflect additional
303 * validity checks performed by annotation processors. For
304 * example, consider the simple annotation:
305 *
306 * <blockquote>
307 * <pre>
308 * @MersennePrime {
309 * int value();
310 * }
311 * </pre>
312 * </blockquote>
313 *
314 * (A Mersenne prime is prime number of the form
315 * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
316 * for this annotation type, a list of all such primes in the
317 * {@code int} range could be returned without examining any other
318 * arguments to {@code getCompletions}:
319 *
320 * <blockquote>
321 * <pre>
322 * import static javax.annotation.processing.Completions.*;
323 * ...
324 * return Arrays.asList({@link Completions#of(String) of}("3"),
325 * of("7"),
326 * of("31"),
327 * of("127"),
328 * of("8191"),
329 * of("131071"),
330 * of("524287"),
331 * of("2147483647"));
332 * </pre>
333 * </blockquote>
334 *
335 * A more informative set of completions would include the number
336 * of each prime:
337 *
338 * <blockquote>
339 * <pre>
340 * return Arrays.asList({@link Completions#of(String, String) of}("3", "M2"),
341 * of("7", "M3"),
342 * of("31", "M5"),
343 * of("127", "M7"),
344 * of("8191", "M13"),
345 * of("131071", "M17"),
346 * of("524287", "M19"),
347 * of("2147483647", "M31"));
348 * </pre>
349 * </blockquote>
350 *
351 * However, if the {@code userText} is available, it can be checked
352 * to see if only a subset of the Mersenne primes are valid. For
353 * example, if the user has typed
354 *
355 * <blockquote>
356 * <code>
357 * @MersennePrime(1
358 * </code>
359 * </blockquote>
360 *
361 * the value of {@code userText} will be {@code "1"}; and only
362 * two of the primes are possible completions:
363 *
364 * <blockquote>
365 * <pre>
366 * return Arrays.asList(of("127", "M7"),
367 * of("131071", "M17"));
368 * </pre>
369 * </blockquote>
370 *
371 * Sometimes no valid completion is possible. For example, there
372 * is no in-range Mersenne prime starting with 9:
373 *
374 * <blockquote>
375 * <code>
376 * @MersennePrime(9
377 * </code>
378 * </blockquote>
379 *
380 * An appropriate response in this case is to either return an
381 * empty list of completions,
382 *
383 * <blockquote>
384 * <pre>
385 * return Collections.emptyList();
386 * </pre>
387 * </blockquote>
388 *
389 * or a single empty completion with a helpful message
390 *
391 * <blockquote>
392 * <pre>
393 * return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
394 * </pre>
395 * </blockquote>
396 *
397 * @param element the element being annotated
398 * @param annotation the (perhaps partial) annotation being
399 * applied to the element
400 * @param member the annotation member to return possible completions for
401 * @param userText source code text to be completed
402 *
403 * @return suggested completions to the annotation
404 */
405 Iterable<? extends Completion> getCompletions(Element element,
406 AnnotationMirror annotation,
407 ExecutableElement member,
408 String userText);
409 }