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 * @version 1.19 07/05/05
164 * @since 1.6
165 */
166 public interface Processor {
167 /**
168 * Returns the options recognized by this processor. An
169 * implementation of the processing tool must provide a way to
170 * pass processor-specific options distinctly from options passed
171 * to the tool itself, see {@link ProcessingEnvironment#getOptions
172 * getOptions}.
173 *
174 * <p>Each string returned in the set must be a period separated
175 * sequence of {@linkplain
176 * javax.lang.model.SourceVersion#isIdentifier identifiers}:
177 *
178 * <blockquote>
179 * <dl>
180 * <dt><i>SupportedOptionString:</i>
181 * <dd><i>Identifiers</i>
182 * <p>
183 * <dt><i>Identifiers:</i>
184 * <dd> <i>Identifier</i>
185 * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i>
186 * <p>
187 * <dt><i>Identifier:</i>
188 * <dd>Syntactic identifier, including keywords and literals
189 * </dl>
190 * </blockquote>
191 *
192 * <p> A tool might use this information to determine if any
193 * options provided by a user are unrecognized by any processor,
194 * in which case it may wish to report a warning.
195 *
196 * @return the options recognized by this processor or an
197 * empty collection if none
198 * @see javax.annotation.processing.SupportedOptions
199 */
200 Set<String> getSupportedOptions();
201
202 /**
203 * Returns the names of the annotation types supported by this
204 * processor. An element of the result may be the canonical
205 * (fully qualified) name of a supported annotation type.
206 * Alternately it may be of the form "<tt><i>name</i>.*</tt>"
207 * representing the set of all annotation types with canonical
208 * names beginning with "<tt><i>name.</i></tt>". Finally, {@code
209 * "*"} by itself represents the set of all annotation types,
210 * including the empty set. Note that a processor should not
211 * claim {@code "*"} unless it is actually processing all files;
212 * claiming unnecessary annotations may cause a performance
213 * slowdown in some environments.
214 *
215 * <p>Each string returned in the set must be accepted by the
216 * following grammar:
217 *
218 * <blockquote>
219 * <dl>
220 * <dt><i>SupportedAnnotationTypeString:</i>
221 * <dd><i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub>
222 * <dd><tt>*</tt>
223 * <p>
224 * <dt><i>DotStar:</i>
225 * <dd><tt>.</tt> <tt>*</tt>
226 * </dl>
227 * </blockquote>
228 *
229 * where <i>TypeName</i> is as defined in the <i>Java Language Specification</i>.
230 *
231 * @return the names of the annotation types supported by this processor
232 * @see javax.annotation.processing.SupportedAnnotationTypes
233 * @jls3 3.8 Identifiers
234 * @jls3 6.5.5 Meaning of Type Names
235 */
236 Set<String> getSupportedAnnotationTypes();
237
238 /**
239 * Returns the latest source version supported by this annotation
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
295 * null}, {@code annotation} and {@code member} may be {@code
296 * null}. Processors may not throw a {@code NullPointerException}
297 * if some parameters are {@code null}; if a processor has no
298 * completions to offer based on the provided information, an
299 * empty iterable can be returned. The processor may also return
300 * a single completion with an empty value string and a message
301 * describing why there are no completions.
302 *
303 * <p>Completions are informative and may reflect additional
304 * validity checks performed by annotation processors. For
305 * example, consider the simple annotation:
306 *
307 * <blockquote>
308 * <pre>
309 * @MersennePrime {
310 * int value();
311 * }
312 * </pre>
313 * </blockquote>
314 *
315 * (A Mersenne prime is prime number of the form
316 * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
317 * for this annotation type, a list of all such primes in the
318 * {@code int} range could be returned without examining any other
319 * arguments to {@code getCompletions}:
320 *
321 * <blockquote>
322 * <pre>
323 * import static javax.annotation.processing.Completions.*;
324 * ...
325 * return Arrays.asList({@link Completions#of(String) of}("3"),
326 * of("7"),
327 * of("31"),
328 * of("127"),
329 * of("8191"),
330 * of("131071"),
331 * of("524287"),
332 * of("2147483647"));
333 * </pre>
334 * </blockquote>
335 *
336 * A more informative set of completions would include the number
337 * of each prime:
338 *
339 * <blockquote>
340 * <pre>
341 * return Arrays.asList({@link Completions#of(String, String) of}("3", "M2"),
342 * of("7", "M3"),
343 * of("31", "M5"),
344 * of("127", "M7"),
345 * of("8191", "M13"),
346 * of("131071", "M17"),
347 * of("524287", "M19"),
348 * of("2147483647", "M31"));
349 * </pre>
350 * </blockquote>
351 *
352 * However, if the {@code userText} is available, it can be checked
353 * to see if only a subset of the Mersenne primes are valid. For
354 * example, if the user has typed
355 *
356 * <blockquote>
357 * <code>
358 * @MersennePrime(1
359 * </code>
360 * </blockquote>
361 *
362 * the value of {@code userText} will be {@code "1"}; and only
363 * two of the primes are possible completions:
364 *
365 * <blockquote>
366 * <pre>
367 * return Arrays.asList(of("127", "M7"),
368 * of("131071", "M17"));
369 * </pre>
370 * </blockquote>
371 *
372 * Sometimes no valid completion is possible. For example, there
373 * is no in-range Mersenne prime starting with 9:
374 *
375 * <blockquote>
376 * <code>
377 * @MersennePrime(9
378 * </code>
379 * </blockquote>
380 *
381 * An appropriate response in this case is to either return an
382 * empty list of completions,
383 *
384 * <blockquote>
385 * <pre>
386 * return Collections.emptyList();
387 * </pre>
388 * </blockquote>
389 *
390 * or a single empty completion with a helpful message
391 *
392 * <blockquote>
393 * <pre>
394 * return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));
395 * </pre>
396 * </blockquote>
397 *
398 * @param element the element being annotated
399 * @param annotation the (perhaps partial) annotation being
400 * applied to the element
401 * @param member the annotation member to return possible completions for
402 * @param userText source code text to be completed
403 *
404 * @return suggested completions to the annotation
405 */
406 Iterable<? extends Completion> getCompletions(Element element,
407 AnnotationMirror annotation, ExecutableElement member,
408 String userText);
409 }
|