Processor


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