1 /* 2 * Copyright (c) 2005, 2020, 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.util.Elements; 30 import javax.lang.model.AnnotatedConstruct; 31 import javax.lang.model.element.*; 32 import javax.lang.model.SourceVersion; 33 34 /** 35 * The interface for an annotation processor. 36 * 37 * <p>Annotation processing happens in a sequence of {@linkplain 38 * javax.annotation.processing.RoundEnvironment rounds}. On each 39 * round, a processor may be asked to {@linkplain #process process} a 40 * subset of the annotations found on the source and class files 41 * produced by a prior round. The inputs to the first round of 42 * processing are the initial inputs to a run of the tool; these 43 * initial inputs can be regarded as the output of a virtual zeroth 44 * round of processing. If a processor was asked to process on a 45 * given round, it will be asked to process on subsequent rounds, 46 * including the last round, even if there are no annotations for it 47 * to process. The tool infrastructure may also ask a processor to 48 * process files generated implicitly by the tool's operation. 49 * 50 * <p> Each implementation of a {@code Processor} must provide a 51 * public no-argument constructor to be used by tools to instantiate 52 * the processor. The tool infrastructure will interact with classes 53 * implementing this interface as follows: 54 * 55 * <ol> 56 * 57 * <li>If an existing {@code Processor} object is not being used, to 58 * create an instance of a processor the tool calls the no-arg 59 * constructor of the processor class. 60 * 61 * <li>Next, the tool calls the {@link #init init} method with 62 * an appropriate {@link ProcessingEnvironment}. 63 * 64 * <li>Afterwards, the tool calls {@link #getSupportedAnnotationTypes 65 * getSupportedAnnotationTypes}, {@link #getSupportedOptions 66 * getSupportedOptions}, and {@link #getSupportedSourceVersion 67 * getSupportedSourceVersion}. These methods are only called once per 68 * run, not on each round. 69 * 70 * <li>As appropriate, the tool calls the {@link #process process} 71 * method on the {@code Processor} object; a new {@code Processor} 72 * object is <em>not</em> created for each round. 73 * 74 * </ol> 75 * 76 * If a processor object is created and used without the above 77 * protocol being followed, then the processor's behavior is not 78 * defined by this interface specification. 79 * 80 * <p> The tool uses a <i>discovery process</i> to find annotation 81 * processors and decide whether or not they should be run. By 82 * configuring the tool, the set of potential processors can be 83 * controlled. For example, for a {@link javax.tools.JavaCompiler 84 * JavaCompiler} the list of candidate processors to run can be 85 * {@linkplain javax.tools.JavaCompiler.CompilationTask#setProcessors 86 * set directly} or controlled by a {@linkplain 87 * javax.tools.StandardLocation#ANNOTATION_PROCESSOR_PATH search path} 88 * used for a {@linkplain java.util.ServiceLoader service-style} 89 * lookup. Other tool implementations may have different 90 * configuration mechanisms, such as command line options; for 91 * details, refer to the particular tool's documentation. Which 92 * processors the tool asks to {@linkplain #process run} is a function 93 * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em> 94 * on the {@linkplain 95 * RoundEnvironment#getRootElements root elements}, what {@linkplain 96 * #getSupportedAnnotationTypes annotation types a processor 97 * supports}, and whether or not a processor {@linkplain #process 98 * claims the annotation types it processes}. A processor will be asked to 99 * process a subset of the annotation types it supports, possibly an 100 * empty set. 101 * 102 * For a given round, the tool computes the set of annotation types 103 * that are present on the elements enclosed within the root elements. 104 * If there is at least one annotation type present, then as 105 * processors claim annotation types, they are removed from the set of 106 * unmatched annotation types. When the set is empty or no more 107 * processors are available, the round has run to completion. If 108 * there are no annotation types present, annotation processing still 109 * occurs but only <i>universal processors</i> which support 110 * processing all annotation types, {@code "*"}, can claim the (empty) 111 * set of annotation types. 112 * 113 * <p>An annotation type is considered present if there is at least 114 * one annotation of that type present on an element enclosed within 115 * the root elements of a round. For this purpose, a type parameter is 116 * considered to be enclosed by its {@linkplain 117 * TypeParameterElement#getGenericElement generic 118 * element}. 119 120 * For this purpose, a package element is <em>not</em> considered to 121 * enclose the top-level types within that package. (A root element 122 * representing a package is created when a {@code package-info} file 123 * is processed.) Likewise, for this purpose, a module element is 124 * <em>not</em> considered to enclose the packages within that 125 * module. (A root element representing a module is created when a 126 * {@code module-info} file is processed.) 127 * 128 * Annotations on {@linkplain 129 * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to 130 * annotations on elements, are ignored when computing whether or not 131 * an annotation type is present. 132 * 133 * <p>An annotation is <em>present</em> if it meets the definition of being 134 * present given in {@link AnnotatedConstruct}. In brief, an 135 * annotation is considered present for the purposes of discovery if 136 * it is directly present or present via inheritance. An annotation is 137 * <em>not</em> considered present by virtue of being wrapped by a 138 * container annotation. Operationally, this is equivalent to an 139 * annotation being present on an element if and only if it would be 140 * included in the results of {@link 141 * Elements#getAllAnnotationMirrors(Element)} called on that element. Since 142 * annotations inside container annotations are not considered 143 * present, to properly process {@linkplain 144 * java.lang.annotation.Repeatable repeatable annotation types}, 145 * processors are advised to include both the repeatable annotation 146 * type and its containing annotation type in the set of {@linkplain 147 * #getSupportedAnnotationTypes() supported annotation types} of a 148 * processor. 149 * 150 * <p>Note that if a processor supports {@code "*"} and returns {@code 151 * true}, all annotations are claimed. Therefore, a universal 152 * processor being used to, for example, implement additional validity 153 * checks should return {@code false} so as to not prevent other such 154 * checkers from being able to run. 155 * 156 * <p>If a processor throws an uncaught exception, the tool may cease 157 * other active annotation processors. If a processor raises an 158 * error, the current round will run to completion and the subsequent 159 * round will indicate an {@linkplain RoundEnvironment#errorRaised 160 * error was raised}. Since annotation processors are run in a 161 * cooperative environment, a processor should throw an uncaught 162 * exception only in situations where no error recovery or reporting 163 * is feasible. 164 * 165 * <p>The tool environment is not required to support annotation 166 * processors that access environmental resources, either {@linkplain 167 * RoundEnvironment per round} or {@linkplain ProcessingEnvironment 168 * cross-round}, in a multi-threaded fashion. 169 * 170 * <p>If the methods that return configuration information about the 171 * annotation processor return {@code null}, return other invalid 172 * input, or throw an exception, the tool infrastructure must treat 173 * this as an error condition. 174 * 175 * <p>To be robust when running in different tool implementations, an 176 * annotation processor should have the following properties: 177 * 178 * <ol> 179 * 180 * <li>The result of processing a given input is not a function of the presence or absence 181 * of other inputs (orthogonality). 182 * 183 * <li>Processing the same input produces the same output (consistency). 184 * 185 * <li>Processing input <i>A</i> followed by processing input <i>B</i> 186 * is equivalent to processing <i>B</i> then <i>A</i> 187 * (commutativity) 188 * 189 * <li>Processing an input does not rely on the presence of the output 190 * of other annotation processors (independence) 191 * 192 * </ol> 193 * 194 * <p>The {@link Filer} interface discusses restrictions on how 195 * processors can operate on files. 196 * 197 * @apiNote Implementors of this interface may find it convenient 198 * to extend {@link AbstractProcessor} rather than implementing this 199 * interface directly. 200 * 201 * @author Joseph D. Darcy 202 * @author Scott Seligman 203 * @author Peter von der Ahé 204 * @since 1.6 205 */ 206 public interface Processor { 207 /** 208 * Returns the options recognized by this processor. An 209 * implementation of the processing tool must provide a way to 210 * pass processor-specific options distinctly from options passed 211 * to the tool itself, see {@link ProcessingEnvironment#getOptions 212 * getOptions}. 213 * 214 * <p>Each string returned in the set must be a period separated 215 * sequence of {@linkplain 216 * javax.lang.model.SourceVersion#isIdentifier identifiers}: 217 * 218 * <blockquote> 219 * <dl> 220 * <dt><i>SupportedOptionString:</i> 221 * <dd><i>Identifiers</i> 222 * 223 * <dt><i>Identifiers:</i> 224 * <dd> <i>Identifier</i> 225 * <dd> <i>Identifier</i> {@code .} <i>Identifiers</i> 226 * 227 * <dt><i>Identifier:</i> 228 * <dd>Syntactic identifier, including keywords and literals 229 * </dl> 230 * </blockquote> 231 * 232 * <p> A tool might use this information to determine if any 233 * options provided by a user are unrecognized by any processor, 234 * in which case it may wish to report a warning. 235 * 236 * @return the options recognized by this processor or an 237 * empty set if none 238 * @see javax.annotation.processing.SupportedOptions 239 */ 240 Set<String> getSupportedOptions(); 241 242 /** 243 * Returns the names of the annotation types supported by this 244 * processor. An element of the result may be the canonical 245 * (fully qualified) name of a supported annotation type. 246 * Alternately it may be of the form "<code><i>name</i>.*</code>" 247 * representing the set of all annotation types with canonical 248 * names beginning with "<code><i>name.</i></code>". 249 * 250 * In either of those cases, the name of the annotation type can 251 * be optionally preceded by a module name followed by a {@code 252 * "/"} character. For example, if a processor supports {@code 253 * "a.B"}, this can include multiple annotation types named {@code 254 * a.B} which reside in different modules. To only support {@code 255 * a.B} in the {@code foo} module, instead use {@code "foo/a.B"}. 256 * 257 * If a module name is included, only an annotation in that module 258 * is matched. In particular, if a module name is given in an 259 * environment where modules are not supported, such as an 260 * annotation processing environment configured for a {@linkplain 261 * javax.annotation.processing.ProcessingEnvironment#getSourceVersion 262 * source version} without modules, then the annotation types with 263 * a module name do <em>not</em> match. 264 * 265 * Finally, {@code "*"} by itself represents the set of all 266 * annotation types, including the empty set. Note that a 267 * processor should not claim {@code "*"} unless it is actually 268 * processing all files; claiming unnecessary annotations may 269 * cause a performance slowdown in some environments. 270 * 271 * <p>Each string returned in the set must be accepted by the 272 * following grammar: 273 * 274 * <blockquote> 275 * <dl> 276 * <dt><i>SupportedAnnotationTypeString:</i> 277 * <dd><i>ModulePrefix</i><sub><i>opt</i></sub> <i>TypeName</i> <i>DotStar</i><sub><i>opt</i></sub> 278 * <dd><code>*</code> 279 * 280 * <dt><i>ModulePrefix:</i> 281 * <dd><i>ModuleName</i> <code>/</code> 282 * 283 * <dt><i>DotStar:</i> 284 * <dd><code>.</code> <code>*</code> 285 * </dl> 286 * </blockquote> 287 * 288 * where <i>TypeName</i> and <i>ModuleName</i> are as defined in 289 * <cite>The Java Language Specification</cite> 290 * ({@jls 6.5 Determining the Meaning of a Name}). 291 * 292 * @apiNote When running in an environment which supports modules, 293 * processors are encouraged to include the module prefix when 294 * describing their supported annotation types. The method {@link 295 * AbstractProcessor#getSupportedAnnotationTypes 296 * AbstractProcessor.getSupportedAnnotationTypes} provides support 297 * for stripping off the module prefix when running in an 298 * environment without modules. 299 * 300 * @return the names of the annotation types supported by this processor 301 * or an empty set if none 302 * @see javax.annotation.processing.SupportedAnnotationTypes 303 * @jls 3.8 Identifiers 304 */ 305 Set<String> getSupportedAnnotationTypes(); 306 307 /** 308 * Returns the latest source version supported by this annotation 309 * processor. 310 * 311 * @return the latest source version supported by this annotation 312 * processor. 313 * @see javax.annotation.processing.SupportedSourceVersion 314 * @see ProcessingEnvironment#getSourceVersion 315 */ 316 SourceVersion getSupportedSourceVersion(); 317 318 /** 319 * Initializes the processor with the processing environment. 320 * 321 * @param processingEnv environment for facilities the tool framework 322 * provides to the processor 323 */ 324 void init(ProcessingEnvironment processingEnv); 325 326 /** 327 * Processes a set of annotation types on type elements 328 * originating from the prior round and returns whether or not 329 * these annotation types are claimed by this processor. If {@code 330 * true} is returned, the annotation types are claimed and subsequent 331 * processors will not be asked to process them; if {@code false} 332 * is returned, the annotation types are unclaimed and subsequent 333 * processors may be asked to process them. A processor may 334 * always return the same boolean value or may vary the result 335 * based on its own chosen criteria. 336 * 337 * <p>The input set will be empty if the processor supports {@code 338 * "*"} and the root elements have no annotations. A {@code 339 * Processor} must gracefully handle an empty set of annotations. 340 * 341 * @param annotations the annotation types requested to be processed 342 * @param roundEnv environment for information about the current and prior round 343 * @return whether or not the set of annotation types are claimed by this processor 344 */ 345 boolean process(Set<? extends TypeElement> annotations, 346 RoundEnvironment roundEnv); 347 348 /** 349 * Returns to the tool infrastructure an iterable of suggested 350 * completions to an annotation. Since completions are being asked 351 * for, the information provided about the annotation may be 352 * incomplete, as if for a source code fragment. A processor may 353 * return an empty iterable. Annotation processors should focus 354 * their efforts on providing completions for annotation members 355 * with additional validity constraints known to the processor, for 356 * example an {@code int} member whose value should lie between 1 357 * and 10 or a string member that should be recognized by a known 358 * grammar, such as a regular expression or a URL. 359 * 360 * <p>Since incomplete programs are being modeled, some of the 361 * parameters may only have partial information or may be {@code 362 * null}. At least one of {@code element} and {@code userText} 363 * must be non-{@code null}. If {@code element} is non-{@code null}, 364 * {@code annotation} and {@code member} may be {@code 365 * null}. Processors may not throw a {@code NullPointerException} 366 * if some parameters are {@code null}; if a processor has no 367 * completions to offer based on the provided information, an 368 * empty iterable can be returned. The processor may also return 369 * a single completion with an empty value string and a message 370 * describing why there are no completions. 371 * 372 * <p>Completions are informative and may reflect additional 373 * validity checks performed by annotation processors. For 374 * example, consider the simple annotation: 375 * 376 * <blockquote> 377 * <pre> 378 * @MersennePrime { 379 * int value(); 380 * } 381 * </pre> 382 * </blockquote> 383 * 384 * (A Mersenne prime is prime number of the form 385 * 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror} 386 * for this annotation type, a list of all such primes in the 387 * {@code int} range could be returned without examining any other 388 * arguments to {@code getCompletions}: 389 * 390 * <blockquote> 391 * <pre> 392 * import static javax.annotation.processing.Completions.*; 393 * ... 394 * return List.of({@link Completions#of(String) of}("3"), 395 * of("7"), 396 * of("31"), 397 * of("127"), 398 * of("8191"), 399 * of("131071"), 400 * of("524287"), 401 * of("2147483647")); 402 * </pre> 403 * </blockquote> 404 * 405 * A more informative set of completions would include the number 406 * of each prime: 407 * 408 * <blockquote> 409 * <pre> 410 * return List.of({@link Completions#of(String, String) of}("3", "M2"), 411 * of("7", "M3"), 412 * of("31", "M5"), 413 * of("127", "M7"), 414 * of("8191", "M13"), 415 * of("131071", "M17"), 416 * of("524287", "M19"), 417 * of("2147483647", "M31")); 418 * </pre> 419 * </blockquote> 420 * 421 * However, if the {@code userText} is available, it can be checked 422 * to see if only a subset of the Mersenne primes are valid. For 423 * example, if the user has typed 424 * 425 * <blockquote> 426 * <code> 427 * @MersennePrime(1 428 * </code> 429 * </blockquote> 430 * 431 * the value of {@code userText} will be {@code "1"}; and only 432 * two of the primes are possible completions: 433 * 434 * <blockquote> 435 * <pre> 436 * return Arrays.asList(of("127", "M7"), 437 * of("131071", "M17")); 438 * </pre> 439 * </blockquote> 440 * 441 * Sometimes no valid completion is possible. For example, there 442 * is no in-range Mersenne prime starting with 9: 443 * 444 * <blockquote> 445 * <code> 446 * @MersennePrime(9 447 * </code> 448 * </blockquote> 449 * 450 * An appropriate response in this case is to either return an 451 * empty list of completions, 452 * 453 * <blockquote> 454 * <pre> 455 * return Collections.emptyList(); 456 * </pre> 457 * </blockquote> 458 * 459 * or a single empty completion with a helpful message 460 * 461 * <blockquote> 462 * <pre> 463 * return Arrays.asList(of("", "No in-range Mersenne primes start with 9")); 464 * </pre> 465 * </blockquote> 466 * 467 * @param element the element being annotated 468 * @param annotation the (perhaps partial) annotation being 469 * applied to the element 470 * @param member the annotation member to return possible completions for 471 * @param userText source code text to be completed 472 * 473 * @return suggested completions to the annotation 474 */ 475 Iterable<? extends Completion> getCompletions(Element element, 476 AnnotationMirror annotation, 477 ExecutableElement member, 478 String userText); 479 }