diff options
Diffstat (limited to 'javax')
| -rw-r--r-- | javax/annotation/processing/Processor.java | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/javax/annotation/processing/Processor.java b/javax/annotation/processing/Processor.java new file mode 100644 index 000000000..af790546c --- /dev/null +++ b/javax/annotation/processing/Processor.java @@ -0,0 +1,190 @@ +/* Processor.java -- An annotation processor. + Copyright (C) 2012 Free Software Foundation, Inc. + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ + +package javax.annotation.processing; + +import java.util.Set; + +import javax.lang.model.SourceVersion; +import javax.lang.model.element.TypeElement; + +/** + * <p>Provides the interface for an annotation processor.</p> + * <p>Annotation processing is divided into a series of rounds, + * with the input for each round being a subset of the output + * from the previous round. The input for the initial round + * are those provided to the tool by the user, but, for the + * purposes of operation, can be thought of as coming from a + * virtual preceding round, as the behaviour is the same. + * Once a processor is asked to process inputs in a particular + * round, it is asked to do so in all subsequent rounds, even + * if there are no annotations left for it to process. These + * inputs can include files generated by the tool's operation.</p> + * <p>Annotation processors are found using a tool-specific + * discovery method which may involve them being named directly + * or discovered via a service-based lookup. The processors which + * are actually used are determined by which of the annotations present + * on the root elements are supported by the processor and whether or + * not it claims them. Claimed annotation types are removed from + * the set of unmatched annotations and are not passed to other + * processors. A round is complete once the set is empty or no + * more processors are available. If there are no annotation types + * on the root elements (i.e. the set is empty to begin with), then + * only <emph>universal processors</emph> (those which accept {@code "*"}) + * are run.</p> + * <h2>Implementing an Annotation Processor</h2> + * <p>The tool infrastructure expects the following from an annotation + * processor:</p> + * <ol> + * <li>It should be able to create an instance of the processor using + * a no-argument constructor and use this same instance for the whole run.</li> + * <li>Once it has created the instance, it calls {@code init} with + * an appropriate {@link ProcessingEnvironment}.</li> + * <li>The tool calls {@link #getSupportedAnnotationTypes}, + * {@link #getSupportedOptions} and {@link #getSupportedSourceVersion} once + * at the start of each run.</li> + * <li>The tool calls {@link #process} on the processor for each round.</li> + * </ol> + * <p>Use outside the above protocol is undefined. A processor supporting + * {@code "*"} and returning {@code true} from the {@code process} method + * will claim all annotations and prevent other processors from running. + * If this is not the intention, then {@code false} should be returned.</p> + * <p>To work well with different tool implementations, the processor + * should make sure the following properties hold:</p> + * <ol> + * <li><strong>Orthogonality</strong>: The result of processing an input + * is not dependent on the presence or not of other inputs.</li> + * <li><strong>Consistency</strong>: Processing the same input should + * always produce the same output.</li> + * <li><strong>Commutativity</strong>: Processing input A then input B + * should be the same as processing input B then input A.</li> + * <li><strong>Independence</strong>: The result of processing an input + * is not dependent on the presence of output from other processors.</li> + * </ol> + * <p>If a processor raises an error, this will be noted and the round + * completed. The subsequent round can then query as to whether an + * error was raised using {@link RoundEnvironment#errorRaised()}. If + * an uncaught exception is raised, the tool may cease the use of other + * annotation processors, so this should be used only in situations where + * the usual error recovery process is infeasible.</p> + * <p>The tool environment need not support annotation processors accessing + * environmental resources, either per round or cross-round, in a multi-threaded + * environment. If a method returns {@code null} or other invalid input, or throws + * an exception, in response to a configuration query, the tool may treat this + * as an error condition.</p> + * <p>The {@link Filer} interface documentation provides more information on how + * files are handled and the restrictions in place. Implementators may find it + * easier to base their implementation on the {@link AbstractProcessor} class + * rather than implementing this interface directly.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Processor +{ + + /** + * <p>Returns the names of the annotation types supported by this + * processor. These can take one of the following forms:</p> + * <ol> + * <li>A canonical fully-qualified type name.</li> + * <li>A partial type name with the suffix {@code .*}</li> + * <li>{@code .*}</li> + * </ol> + * <p>For example, {@code "gnu.classpath.annotations.ProcessMe"} matches + * the specific annotation class, {@code ProcessMe}. Alternatively, + * {@code "gnu.classpath.annotations.*"} matches all annotations under + * the package {@code gnu.classpath.annotations}. Finally, {@code .*} + * matches all annotations.</p> + * <p>Processors should avoid claiming annotations they don't support, + * as this may cause performance issues, and, if they also return + * {@code true} when asked to {@link #process()} them, then they may + * prevent other processors from handling those annotations.</p> + * + * @return the names of the supported annotation types. + * @see SupportedAnnotationTypes + */ + Set<String> getSupportedAnnotationTypes(); + + /** + * Returns the options supported by this tool. Each string + * returned by this method must be a period-separated sequence + * of identifiers, as defined by + * {@link SourceVersion#isIdentifier(CharSequence)}. + * The tool may use this list to work out which options a user + * provides are unsupported and print a warning. + * + * @return the names of the supported options or an empty set if none. + * @see SupportedOptions + */ + Set<String> getSupportedOptions(); + + /** + * Returns the latest source code version supported by this processor. + * + * @return the latest version supported. + * @see SupportedSourceVersion + * @see ProcessingEnvironment#getSourceVersion + */ + SourceVersion getSupportedSourceVersion(); + + /** + * Initialises the processor with the specified environment. + * + * @param env the environment for the annotation processor, which gives + * it with access to facilities provided by the tool. + */ + void init(ProcessingEnvironment env); + + /** + * Processes a set of annotation types originating from the previous + * round (including the virtual zeroth round formed from the user's input). + * The processor may opt to claim these types by returning {@code true}. + * If it does so, the types are claimed and they are not passed to + * subsequent processors. Whether a processor claims types or not may + * vary, dependent on its own criteria. A processor that supports + * all types ({@code "*"}) is expected to gracefully handle the possibility + * of receiving an empty set of annotations. + * + * @param types the annotations to process. + * @param roundEnv information about this and the previous round. + * @return true if the annotations are claimed by this processor, false otherwise. + */ + boolean process(Set<? extends TypeElement> types, RoundEnvironment roundEnv); + +} + |