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 49 * public no-argument constructor to be used by tools to instantiate 50 * the processor. The tool infrastructure will interact with classes 51 * implementing this interface as follows: 52 * 53 * <ol> 54 * 55 * <li>If an existing {@code Processor} object is not being used, to 56 * create an instance of a processor the tool calls the no-arg 57 * constructor of the processor class. 58 * 59 * <li>Next, the tool calls the {@link #init init} method with 60 * an appropriate {@code ProcessingEnvironment}. 61 * 62 * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes 63 * getSupportedAnnotationTypes}, {@link #getSupportedOptions 64 * getSupportedOptions}, and {@link #getSupportedSourceVersion 65 * getSupportedSourceVersion}. These methods are only called once per 66 * run, not on each round. 67 * 68 * <li>As appropriate, the tool calls the {@link #process process} 69 * method on the {@code Processor} object; a new {@code Processor} 70 * object is <em>not</em> created for each round. 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 * 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 229 * <cite>The Java™ Language Specification</cite>. 230 * 231 * @return the names of the annotation types supported by this processor 232 * @see javax.annotation.processing.SupportedAnnotationTypes 233 * @jls 3.8 Identifiers 234 * @jls 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, 408 ExecutableElement member, 409 String userText); 410 }