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: }
|