diff options
Diffstat (limited to 'javax/annotation')
| -rw-r--r-- | javax/annotation/processing/Filer.java | 215 | ||||
| -rw-r--r-- | javax/annotation/processing/FilerException.java | 73 | ||||
| -rw-r--r-- | javax/annotation/processing/Messager.java | 114 | ||||
| -rw-r--r-- | javax/annotation/processing/ProcessingEnvironment.java | 133 | ||||
| -rw-r--r-- | javax/annotation/processing/Processor.java | 190 | ||||
| -rw-r--r-- | javax/annotation/processing/RoundEnvironment.java | 120 |
6 files changed, 845 insertions, 0 deletions
diff --git a/javax/annotation/processing/Filer.java b/javax/annotation/processing/Filer.java new file mode 100644 index 000000000..21b21f807 --- /dev/null +++ b/javax/annotation/processing/Filer.java @@ -0,0 +1,215 @@ +/* Filer.java -- Manages file creation for 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.io.IOException; + +import javax.lang.model.element.Element; + +import javax.tools.JavaFileManager; +import javax.tools.JavaFileObject; +import javax.tools.FileObject; + +/** + * <p>This interface supports the creation of new files by the + * annotation processor. Creating files via this interface means + * that they can be tracked by the annotation processing tool. + * Once the file streams are closed, the tool will automatically + * consider them for processing.</p> + * <p>Files are separated into three types: source files, class + * files and resource files. Two locations are defined; one + * for source files and one for class files (resource files + * may use either). Locations are specified using a relative + * path separated by {@code '/'} and not including the + * segments {@code '.'} and {@code '..'} so that they may only + * refer to subdirectories. A valid relative name must match + * the "path-rootless" rule of RFC 3986, section 3.3.</p> + * <p>The file creation methods take a variable number of + * originating elements, which can be used by the tool to + * handle dependency management. For example, if a + * file is generated due to the presence of a particular + * method, the element representing that method may be + * specified as an originating element. Whether this + * information is used by the tool or not is left down + * to the implementator.</p> + * <p>Each run of the annotation processing tool may only + * create a file with a given pathname once. Attempts + * to create the same file a second time will result in + * a {@link FilerException}. The same behaviour results + * from trying to overwrite the initial source files, which + * are classed as being created in the zeroth round of + * processing. The same exception will be thrown if + * the same name is used for both a source file and a + * class file.</p> + * <p>Processors must not knowingly attempt to overwrite + * files that weren't generated by themselves or a similar + * tool. Similarly, the user invoking the tool should + * not configure it so that it will end up overwriting + * files that weren't generated. A {@code Filer} + * implementation may include safeguards so as not to + * overwrite class files such as {@code java.lang.Object}.</p> + * <p>The {@link javax.lang.annotation.Generated} + * annotation is available to denote generated files + * if needed. Some of the effect of overwriting files may + * be achieved by using a decorator-style design + * pattern and either a generated superclass or a series + * of generated subclasses. In the latter case, + * the class would provide the appropriate generated + * subclass via the factory pattern.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Filer +{ + + /** + * Returns a {@link JavaFileObject} for writing a class + * file. The name and location of the created file are + * based on the specified type name. The location used + * is relative to the root location for class files. + * A class file may be created for a package by appending + * the suffix {@code ".package-info"} to the name. The + * contents of the class file should be compatible with + * source version being used for this run of the annotation + * processor. + * + * @param name the name of the type (or package if + * the {@code ".package-info"} suffix) to create + * a class file for. + * @param elements program elements associated with this class + * file. May be {@code null} or incomplete. + * @return access to the new class file via a {@link JavaFileObject}. + * @throws FilerException if the same pathname has already been used, + * the same type has already been created or + * the name is invalid. + * @throws IOException if an I/O error occurs. + */ + JavaFileObject createClassFile(CharSequence name, Element... elements) + throws IOException; + + /** + * <p>Returns a {@link FileObject} for writing a resource file. + * The name and location of the created file are determined + * by combining the given location (either that used by class + * files, source files or another location supported by the + * implementation), the name of a package in which the resource + * should live (if any), and the specified name.</p> + * <p>Files created by this method are not registered for annotation + * processing.</p> + * + * @param location the location to use for the resource. Can be + * {@link javax.tools.StandardLocation#CLASS_OUTPUT}, + * {@link javax.tools.StandardLocation#SOURCE_OUTPUT}, + * or another location supported by the implementation. + * @param pkg the package which should contain the resource, or the + * empty string if one is not used. + * @param relName the final path components of the file name, which will + * be relative to the location and (if specified) the package. + * @param elements program elements associated with this resource + * file. May be {@code null} or incomplete. + * @return access to the new resource file via a {@link FileObject}. + * @throws FilerException if the same pathname has already been used. + * @throws IOException if an I/O error occurs. + * @throws IllegalArgumentException if the location specified is not supported, + * or {@code relName} is not relative. + */ + FileObject createResource(JavaFileManager.Location location, + CharSequence pkg, CharSequence relName, + Element... elements) + throws IOException; + + /** + * <p>Returns a {@link JavaFileObject} for writing a source + * file. The name and location of the created file are + * based on the specified type name. If more than one + * type is being declared, the top-level one should be used. + * The location used is relative to the root location for + * source files. A source file may be created for a package by + * appending the suffix {@code ".package-info"} to the name. The + * contents of the source file should be compatible with + * source version being used for this run of the annotation + * processor.</p> + * <p>The character set used by the {@link java.io.OutputStream} + * of the returned object is determined by the implementation, + * and may be set using either the platform default or by an + * option passed to the annotation processing tool. To override + * this, users can wrap the stream in an + * {@link java.io.OutputStreamWriter}.</p> + * + * @param name the fully-qualified name of the type (or package if + * the {@code ".package-info"} suffix) to create + * a source file for. + * @param elements program elements associated with this source + * file. May be {@code null} or incomplete. + * @return access to the new source file via a {@link JavaFileObject}. + * @throws FilerException if the same pathname has already been used, + * the same type has already been created or + * the name is invalid. + * @throws IOException if an I/O error occurs. + */ + JavaFileObject createSourceFile(CharSequence name, Element... elements) + throws IOException; + + /** + * Returns a {@link FileObject} for reading a resource file. + * The name and location of the file to read are determined + * by combining the given location (either that used by class + * files, source files or another location supported by the + * implementation), the name of a package in which the resource + * lives (if any), and the specified name. + * + * @param location the location to use for the resource. Can be + * {@link javax.tools.StandardLocation#CLASS_OUTPUT}, + * {@link javax.tools.StandardLocation#SOURCE_OUTPUT}, + * or another location supported by the implementation. + * @param pkg the package which contains the resource, or the + * empty string if one is not used. + * @param relName the final path components of the file name, which will + * be relative to the location and (if specified) the package. + * @return access to the new resource file via a {@link FileObject}. + * @throws FilerException if the same pathname is open for writing. + * @throws IOException if an I/O error occurs. + * @throws IllegalArgumentException if the location specified is not supported, + * or {@code relName} is not relative. + */ + FileObject getResource(JavaFileManager.Location location, + CharSequence pkg, CharSequence relName) + throws IOException; + +} diff --git a/javax/annotation/processing/FilerException.java b/javax/annotation/processing/FilerException.java new file mode 100644 index 000000000..fd00665e3 --- /dev/null +++ b/javax/annotation/processing/FilerException.java @@ -0,0 +1,73 @@ +/* FilerException.java -- Attempt to violate a Filer guarantee. + 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.io.IOException; + +/** + * Thrown when a {@link Filer} detects an attempt to violate one + * of its guarantees. This may be an attempt to create the same + * file multiple times, an attempt to create multiple files of the + * same type or an attempt to create a file for a type with an + * invalid name. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public class FilerException + extends IOException +{ + + /** + * Compatible with OpenJDK 1.6+ + */ + private static final long serialVersionUID = 8426423106453163293L; + + /** + * Constructs a new {@code FilerException} with the specified + * message. The message should contain the name of the file + * attempting to be opened. + * + * @param message the reason for the exception, or {@code null}. + */ + public FilerException(String message) + { + super(message); + } + +} diff --git a/javax/annotation/processing/Messager.java b/javax/annotation/processing/Messager.java new file mode 100644 index 000000000..884b5b374 --- /dev/null +++ b/javax/annotation/processing/Messager.java @@ -0,0 +1,114 @@ +/* Messager.java -- Allows an annotation processor to report messages. + 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 javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.AnnotationValue; +import javax.lang.model.element.Element; + +import static javax.tools.Diagnostic.Kind; + +/** + * Provides a way for an annotation processor to report + * messages to the user. Messages may use elements, + * annotations and annotation values to provide a location + * hint, but these may be either unavailable or only + * approximate. Printing a message of kind + * {@link javax.tools.Diagnostic,Kind#ERROR} will cause + * an error to be raised. How the messages are displayed + * is left to the implementor; it may be a simple use of + * {@code System.out} and/or {@code System.err} or something + * more graphical if the application has a user interface. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Messager +{ + + /** + * Prints a message of the specified kind. + * + * @param kind the kind of message to print. + * @param message the message to print. + */ + void printMessage(Kind kind, CharSequence message); + + /** + * Prints a message of the specified kind at + * the location of the given element. + * + * @param kind the kind of message to print. + * @param message the message to print. + * @param element the element to use for positioning. + */ + void printMessage(Kind kind, CharSequence message, + Element element); + + /** + * Prints a message of the specified kind at the + * location of the annotation mirror of the given + * annotated element. + * + * @param kind the kind of message to print. + * @param message the message to print. + * @param element the annotated element. + * @param annotation the annotation to use for + * positioning. + */ + void printMessage(Kind kind, CharSequence message, + Element element, + AnnotationMirror annotation); + + /** + * Prints a message of the specified kind at the + * location of the annotation value inside the + * annotation mirror of the given annotated element. + * + * @param kind the kind of message to print. + * @param message the message to print. + * @param element the annotated element. + * @param annotation the annotation containing the value. + * @param value the annotation value to use for positioning. + */ + void printMessage(Kind kind, CharSequence message, + Element element, + AnnotationMirror annotation, + AnnotationValue value); + +} diff --git a/javax/annotation/processing/ProcessingEnvironment.java b/javax/annotation/processing/ProcessingEnvironment.java new file mode 100644 index 000000000..1fe6b29b5 --- /dev/null +++ b/javax/annotation/processing/ProcessingEnvironment.java @@ -0,0 +1,133 @@ +/* ProcessingEnvironment.java -- Links the annotation processor to the framework. + 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.Locale; +import java.util.Map; + +import javax.lang.model.SourceVersion; + +import javax.lang.model.util.Elements; +import javax.lang.model.util.Types; + +/** + * Provides the annotation processor with access to the + * facilities of the framework, such as the + * {@link Filer} for creating files and the + * {@link Messager} for printing messages to the user. + * It is possible to wrap implementations of this interface + * in order to provide additional functionality. However, + * doing so requires also implementing the dependent + * facility objects, such as the {@code Filer}, so that + * these additional changes are reflected throughout. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface ProcessingEnvironment +{ + + /** + * Returns an implementation of a number of utility + * methods which provide additional functionality for + * working with (@link javax.lang.model.element.Element} + * instances. + * + * @return the element utilities. + */ + Elements getElementUtils(); + + /** + * Returns an implementation of the {@link Filer} + * which can be used to create source, class or + * resource files. + * + * @return the filer. + */ + Filer getFiler(); + + /** + * Returns the locale used to localise messages from + * the {@link Messager} or {@code null} if one has not + * been set. + * + * @return the current locale or {@code null} if no + * locale has been setup. + */ + Locale getLocale(); + + /** + * Returns an implementation of the {@link Messager} + * which is used to report back to the user, whether + * that be with errors, warnings or other issues. + * + * @return the messager. + */ + Messager getMessager(); + + /** + * Returns the options passed to the annotation processor + * as a map of option names to values. If an option does + * not have a value, it will map to {@code null}. For + * details of the options themselves, see the documentation + * for the annotation processor. + * + * @return a map of the options passed to the annotation processor. + */ + Map<String,String> getOptions(); + + /** + * Returns the version of Java source code that generated + * source files and class files should conform to. + * + * @return the version of Java code used in generated files. + * @see Processor#getSupportedSourceVersion() + */ + SourceVersion getSourceVersion(); + + /** + * Returns an implementation of a number of utility + * methods which provide additional functionality for + * working with (@link javax.lang.model.type.TypeMirror} + * instances. + * + * @return the type utilities. + */ + Types getTypeUtils(); + +} 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); + +} + diff --git a/javax/annotation/processing/RoundEnvironment.java b/javax/annotation/processing/RoundEnvironment.java new file mode 100644 index 000000000..3be899ac7 --- /dev/null +++ b/javax/annotation/processing/RoundEnvironment.java @@ -0,0 +1,120 @@ +/* RoundEnvironment.java -- Represents a round of annotation processing. + 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.lang.annotation.Annotation; + +import java.util.Set; + +import javax.lang.model.element.Element; +import javax.lang.model.element.TypeElement; + +/** + * Provides information used in a round of annotation processing. + * Annotation processing frameworks should provide an implementation + * of this interface, so that processors can be supplied with an instance + * in order to query information about their environment. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface RoundEnvironment +{ + + /** + * Returns true if the previous round of annotation processing + * raised an error. + * + * @return true if the previous round raised an error. + */ + boolean errorRaised(); + + /** + * Returns the elements annotated with the given annotation type. + * Only the package and type elements, and their constituent + * member, parameter and type parameter elements, included in this + * round of annotation processing are returned. Both root type + * elements and any member type elements nested within them are + * included. The annotation may be used directly or inherited + * by another annotation. Elements in a package are not included + * simply because a package-info file was generated. + * + * @param annotation the annotation type requested. + * @return the elements annotated with the given annotation type + * or an empty set if none were found. + * @throws IllegalArgumentException if @code{annotation} does not + * represent an annotation type. + */ + Set<? extends Element> getElementsAnnotatedWith(Class <? extends Annotation> annotation); + + /** + * Returns the elements annotated with the given annotation type. + * Only the package and type elements, and their constituent + * member, parameter and type parameter elements, included in this + * round of annotation processing are returned. Both root type + * elements and any member type elements nested within them are + * included. The annotation may be used directly or inherited + * by another annotation. Elements in a package are not included + * simply because a package-info file was generated. + * + * @param annotation the annotation type requested. + * @return the elements annotated with the given annotation type + * or an empty set if none were found. + * @throws IllegalArgumentException if @code{annotation} does not + * represent an annotation type. + */ + Set<? extends Element> getElementsAnnotatedWith(TypeElement annotation); + + /** + * Returns the root elements generated by the previous round of + * annotation processing. + * + * @return the elements generated by the previous round or an + * empty set if none were generated. + */ + Set<? extends Element> getRootElements(); + + /** + * Returns true if there will not be another round of processing + * on the elements generated by this round. + * + * @return true if the generated types will not be further processed. + */ + boolean processingOver(); + +} |