diff options
Diffstat (limited to 'javax')
53 files changed, 6846 insertions, 1 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(); + +} diff --git a/javax/lang/model/SourceVersion.java b/javax/lang/model/SourceVersion.java new file mode 100644 index 000000000..e42889dd3 --- /dev/null +++ b/javax/lang/model/SourceVersion.java @@ -0,0 +1,103 @@ +/* SourceVersion.java -- Source versions of the Java programming language. + 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.lang.model; + +/** + * Source versions of the Java programming language. + * Note that this will be extended with additional + * constants to represent new versions. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum SourceVersion +{ + /** The original version of Java. */ RELEASE_0, + /** Java 1.1 */ RELEASE_1, + /** Java 1.2 */ RELEASE_2, + /** Java 1.3 */ RELEASE_3, + /** Java 1.4 */ RELEASE_4, + /** Java 5 */ RELEASE_5, + /** Java 6 */ RELEASE_6; + + /** + * Returns true if {@code name} is a syntactically valid identifier or + * keyword in the latest version of the language. That is, this + * method returns true if the {@link Character#isJavaIdentifierStart(int)} + * holds for the first character and {@link Character#isJavaIdentifierPart(int)} + * for the rest. This matches all regular identifiers, keywords + * and the literals {@code true}, {@code false} and {@code null}. + * + * @param name the name to check. + * @return true if {@code name} represents a valid identifier, keyword or literal. + */ + public static boolean isIdentifier(CharSequence name) + { + int size = name.length(); + if (size > 0 && Character.isJavaIdentifierStart(name.charAt(0))) + { + for (int a = 1; a < size; ++a) + if (!Character.isJavaIdentifierPart(name.charAt(a))) + return false; + return true; + } + return false; + } + + /** + * Returns the latest source version that can be modeled. + * + * @return the latest modelable source version. + */ + public static SourceVersion latest() + { + return RELEASE_6; + } + + /** + * Returns the latest source version fully supported + * by GNU Classpath. Must be at least {@code RELEASE_5}. + * + * @return the latest supported source version. + */ + public static SourceVersion latestSupported() + { + return RELEASE_5; + } + +} diff --git a/javax/lang/model/element/AnnotationMirror.java b/javax/lang/model/element/AnnotationMirror.java new file mode 100644 index 000000000..eeaf688e8 --- /dev/null +++ b/javax/lang/model/element/AnnotationMirror.java @@ -0,0 +1,78 @@ +/* AnnotationMirror.java -- Represents an annotation. + 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.lang.model.element; + +import java.util.Map; + +import javax.lang.model.type.DeclaredType; + +/** + * Represents an annotation. An annotation associates values + * with the elements of an annotation type. Annotations should + * be compared using {@link #equals(Object)}. There is no guarantee + * that the same annotation is always represented by the same + * instance. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface AnnotationMirror +{ + + /** + * Returns the type of this annotation. + * + * @return the type of this annotation. + */ + DeclaredType getAnnotationType(); + + /** + * Returns a map of elements to their values. Only those + * elements explicitly set in the annotation are present; + * default values are not included. To obtain the default + * values as well, use + * {@link javax.lang.model.util.Elements#getElementValuesWithDefaults(AnnotationMirror)} + * A marker annotation, by definition, returns an empty map. + * The order of the elements in the map follows that of the + * source code. + * + * @return the map of elements to values. + */ + Map<? extends ExecutableElement, ? extends AnnotationValue> getElementValues(); + +} diff --git a/javax/lang/model/element/AnnotationValue.java b/javax/lang/model/element/AnnotationValue.java new file mode 100644 index 000000000..d25ce4205 --- /dev/null +++ b/javax/lang/model/element/AnnotationValue.java @@ -0,0 +1,86 @@ +/* AnnotationValue.java -- Represents an annotation value. + 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.lang.model.element; + +/** + * <p>Represents the value of an element in an annotation. This + * may be one of the following types:</p> + * <ul> + * <li>a wrapper class for a primitive type (e.g. {@code Integer} + * for {@code int}.</li> + * <li>{@code String}</li> + * <li>{@code TypeMirror}</li> + * <li>{@code VariableElement} (an enum constant)</li> + * <li>{@code AnnotationMirror}</li> + * <li>{@code List<? extends AnnotationValue>} (an array, + * with elements in the order they were declared)</li> + * </ol> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface AnnotationValue +{ + + /** + * Applies a visitor to this type. + * + * @param <R> the return type of the visitor's methods. + * @param <P> the type of the additional parameter used in the visitor's + * methods. + * @param visitor the visitor to apply to the element. + * @param param the additional parameter to be sent to the visitor. + * @return the return value from the visitor. + */ + <R,P> R accept(AnnotationValueVisitor<R,P> visitor, P param); + + /** + * Returns the value. + * + * @return the value. + */ + Object getValue(); + + /** + * Returns a textual representation of the value. + * + * @return a textual representation. + */ + String toString(); + +} diff --git a/javax/lang/model/element/AnnotationValueVisitor.java b/javax/lang/model/element/AnnotationValueVisitor.java new file mode 100644 index 000000000..74229eb55 --- /dev/null +++ b/javax/lang/model/element/AnnotationValueVisitor.java @@ -0,0 +1,226 @@ +/* AnnotationValueVisitor.java -- A visitor of annotation values. + 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.lang.model.element; + +import java.util.List; + +import javax.lang.model.type.TypeMirror; + +/** + * <p>A visitor for annotation values. Unlike other visitors, such + * as {@link ElementVisitor} and {@link javax.lang.model.type.TypeVisitor}, + * which work on a concrete type hierarchy, this visitor dispatches based + * on the type of data stored in the annotation, some of which don't have + * distinct subclasses for storing them (e.g. primitives like {@code boolean} + * and {@code int}.</p> + * <p> The visitor is used when the specific type is not known at compile + * time. A visitor instance is passed to the + * {@link AnnotationValue#accept(AnnotationValueVisitor,P)} method of + * the type, which then calls the specific {@code visitN} method + * appropriate to that specific type.</p> + * <p>The additional parameter supplied to visitor methods may or + * may not be optional, and so the class is free to throw a + * {@code NullPointerException} if {@code null} is passed as the + * additional parameter.</p> + * <p>As this interface may be extended to accomodate future language + * versions, implementators are encouraged to extend one of the + * appropriate abstract classes rather than implementating this + * interface. However, this interface should be used as the type + * for parameters and return values.</p> + * + * @param <R> the return type of the visitor's methods. {@code Void} + * can be used where there is no return value. + * @param <P> the type of the additional parameter supplied to the visitor's + * methods. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface AnnotationValueVisitor<R,P> +{ + + /** + * A convenience method for use when there is no additional + * parameter to pass. This is equivalent to {@code #visit(value, null)}. + * + * @param value the value to visit. + * @return the return value specific to the visitor. + */ + R visit(AnnotationValue value); + + /** + * Visits a value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visit(AnnotationValue value, P param); + + /** + * Visits an annotation value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitAnnotation(AnnotationMirror value, P param); + + /** + * Visits an array value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitArray(List<? extends AnnotationValue> value, P param); + + /** + * Visits a boolean value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitBoolean(boolean value, P param); + + /** + * Visits a byte value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitByte(byte value, P param); + + /** + * Visits a character value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitChar(char value, P param); + + /** + * Visits a double value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitDouble(double value, P param); + + /** + * Visits an enum value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitEnumConstant(VariableElement value, P param); + + /** + * Visits a float value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitFloat(float value, P param); + + /** + * Visits an int value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitInt(int value, P param); + + /** + * Visits a long value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitLong(long value, P param); + + /** + * Visits a short value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitShort(short value, P param); + + /** + * Visits a {@code String} value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitString(String value, P param); + + /** + * Visits a type value. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitType(TypeMirror value, P param); + + /** + * Visits an unknown type of value. This method is called if + * a new type is added to the hierarchy which isn't yet + * handled by the visitor. + * + * @param value the value to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + * @throws UnknownAnnotationValueException if the implementation + * chooses to. + */ + R visitUnknown(AnnotationValue value, P param); + +} diff --git a/javax/lang/model/element/Element.java b/javax/lang/model/element/Element.java new file mode 100644 index 000000000..507547600 --- /dev/null +++ b/javax/lang/model/element/Element.java @@ -0,0 +1,213 @@ +/* Element.java -- Represents a program element at the language level. + 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.lang.model.element; + +import java.lang.annotation.Annotation; + +import java.util.List; +import java.util.Set; + +import javax.lang.model.type.TypeMirror; + +/** + * <p> + * Represents a program element at the language level. For example, + * an {@code Element} may represent a package, a class or a type + * parameter. Types only present at runtime in the virtual machine + * are not represented. + * </p> + * <p>To compare two instances, use {@link #equals(Object)} as there + * is no guarantee that == will hold. To determine the subtype of + * {@code Element}, use {@link #getKind()} or a visitor, as + * implementations may use the same class to implement multiple + * subinterfaces.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Element +{ + + /** + * Applies a visitor to this element. + * + * @param <R> the return type of the visitor's methods. + * @param <P> the type of the additional parameter used in the visitor's + * methods. + * @param visitor the visitor to apply to the element. + * @param param the additional parameter to be sent to the visitor. + * @return the return value from the visitor. + */ + <R,P> R accept(ElementVisitor<R,P> visitor, P param); + + /** + * <p>Returns {@code true} if this instance represents the same + * element as the one supplied.</p> + * <p>Please note that an element may not be equal to the same + * element provided by a different implementation of this framework, + * as the equivalence comparison may include the use of internal + * state which is inaccessible from the element's methods. This + * is similar to the way {@link Class} objects provided by different + * classloaders are not guaranteed to be equal.</p> + * + * @param obj the object to compare. + * @return {@code true} if {@code this} and {@code obj} represent + * the same element. + */ + boolean equals(Object obj); + + /** + * <p>Returns the element's annotation for the specified annotation type, + * if present, or {@code null} if not. The annotation may be directly + * present on the element or inherited.</p> + * <p>If the annotation contains an element of type {@code Class} or + * {@code Class[]}, attempts to read such an object will result in + * a {@link javax.lang.model.type.MirroredTypeException} or + * {@link javax.lang.model.type.MirroredTypesException} respectively. + * This is because information required to load the class (such as its + * class loader) is unavailable and so it may not be possible to load + * the class at all.</p> + * <p>Note that, unlike other methods in this framework, this method + * operates on runtime information obtained through reflection. + * As a result, the methods of the returned annotation object may + * throw exceptions relating to reflection failures.</p> + * + * @param <A> the type of annotation. + * @param annonType the {@code Class} object representing the annotation type. + * @return an annotation of the specified type, if present, or {@code null}. + * @see #getAnnotationMirrors() + * @see Elements#getAllAnnotationMirrors(Element) + * @see java.lang.reflect.AnnotatedElement#getAnnotation(Class) + * @see java.lang.annotation.AnnotationTypeMismatchException + * @see java.lang.annotation.IncompleteAnnotationException + * @see javax.lang.model.type.MirroredTypeException + * @see javax.lang.model.type.MirroredTypesException + */ + <A extends Annotation> A getAnnotation(Class<A> annonType); + + /** + * Returns the elements directly enclosed by this element. + * For example, a class element encloses constructor, method, + * field and further class elements. The returned list + * includes elements automatically generated by the compiler + * such as the default constructor and {@code values} and + * {@code valueOf} methods present in enumerations. Package + * elements contain class and interface elements, but not + * other packages. All other types of element do not contain + * other elements at this time. + * + * @return the enclosed elements, or an empty list if the + * element has none. + * @see Elements#getAllMembers(TypeElement) + */ + List<? extends Element> getEnclosedElements(); + + /** + * Returns the element that encloses this element. For a top-level + * type, its package is returned. Package and type parameter + * elements return {@code null}. + * + * @return the enclosing element or {@code null} if there isn't one. + * @see Elements#getPackageOf(Element) + */ + Element getEnclosingElement(); + + /** + * Returns the kind of this element. + * + * @return the kind of element. + */ + ElementKind getKind(); + + /** + * Obeys the general contract of {@link java.lang.Object#hashCode()}. + * + * @return a hash code for this element. + * @see #equals(Object) + */ + int hashCode(); + + /** + * Returns the type defined by this element. A generic + * element defines not one type, but a family of types. + * For such elements, a prototypical type is returned + * i.e. the element {@code Set<N extends Number>} will + * return the type {@code Set<N>}. The methods of + * {@link javax.lang.model.util.Types} should be used to + * obtain the full family of types. + * + * @return the type defined by this element. + * @see javax.lang.model.util.Types + */ + TypeMirror asType(); + + /** + * Returns the annotations directly present on this element. + * To obtain inherited annotations as well, call + * the {@link javax.lang.model.util.Elements#getAllAnnotationMirrors()} + * method of {@link javax.lang.model.util.Elements}. + * + * @return the annotations directly present on this element or + * an empty list if there are none. + * @see javax.lang.model.util.ElementFilter + */ + List<? extends AnnotationMirror> getAnnotationMirrors(); + + /** + * Returns the modifiers attached to this element, other than + * annotations e.g. {@code public} or {@code abstract}. If + * there are no modifiers, an empty set is returned. + * + * @return the modifiers of this element. + */ + Set<Modifier> getModifiers(); + + /** + * Returns the simple name of this element i.e. without any + * package prefix. The simple name of a generic type is the + * same as that of the raw variant i.e. {@code Set<E>}'s simple + * name is {@code "Set"}. Constructors are named {@code "<init>"} + * and static initializers {@code "<clinit>"}. Unnamed packages, + * anonymous classes and instance initializers all return the + * empty string, {@code ""}. + * + * @return the simple name of this element. + */ + Name getSimpleName(); + +} diff --git a/javax/lang/model/element/ElementKind.java b/javax/lang/model/element/ElementKind.java new file mode 100644 index 000000000..b1765c547 --- /dev/null +++ b/javax/lang/model/element/ElementKind.java @@ -0,0 +1,119 @@ +/* ElementKind.java -- Represents the kind of an element. + 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.lang.model.element; + +/** + * <p>Represents the kind of an element, such as a class element + * or a field element. This enumeration may be extended with + * further kinds to represent future versions of the language.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum ElementKind +{ + /** An annotation type. */ + ANNOTATION_TYPE, + /** A normal class, not described by a more specific type. */ + CLASS, + /** A constructor */ + CONSTRUCTOR, + /** An enumeration */ + ENUM, + /** A constant field used in an enumeration. */ + ENUM_CONSTANT, + /** A parameter passed to an exception handler. */ + EXCEPTION_PARAMETER, + /** A normal field, not described by a more specific type. */ + FIELD, + /** An instance initializer. */ + INSTANCE_INIT, + /** A normal interface, not described by a more specific type. */ + INTERFACE, + /** A local variable. */ + LOCAL_VARIABLE, + /** A method. */ + METHOD, + /** An element reserved for implementation-specific usage. */ + OTHER, + /** A package. */ + PACKAGE, + /** A parameter passed to a method or constructor. */ + PARAMETER, + /** A static initializer. */ + STATIC_INIT, + /** A type parameter. */ + TYPE_PARAMETER; + + /** + * Returns true if this element is a class i.e. either a + * general {@code CLASS} or the specific {@code ENUM}. + * + * @return true if this kind is either {@code CLASS} or + * {@code ENUM}. + */ + public boolean isClass() + { + return this == CLASS || this == ENUM; + } + + /** + * Returns true if this element is a field i.e. either a + * general {@code FIELD} or the specific {@code ENUM_CONSTANT}. + * + * @return true if this kind is either {@code FIELD} or + * {@code ENUM_CONSTANT}. + */ + public boolean isField() + { + return this == FIELD || this == ENUM_CONSTANT; + } + + /** + * Returns true if this element is a interface i.e. either a + * general {@code INTERFACE} or the specific {@code ANNOTATION_TYPE}. + * + * @return true if this kind is either {@code INTERFACE} or + * {@code ANNOTATION_TYPE}. + */ + public boolean isInterface() + { + return this == INTERFACE || this == ANNOTATION_TYPE; + } + +} diff --git a/javax/lang/model/element/ElementVisitor.java b/javax/lang/model/element/ElementVisitor.java new file mode 100644 index 000000000..133ab5aa5 --- /dev/null +++ b/javax/lang/model/element/ElementVisitor.java @@ -0,0 +1,143 @@ +/* ElementVisitor.java -- A visitor of program elements. + 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.lang.model.element; + +/** + * <p>A visitor for program elements. This is used when the specific + * type of element is not known at compile time. A visitor instance + * is passed to the {@link Element#accept(ElementVisitor,P)} method of + * the element, which then calls the specific {@code visitN} method + * appropriate to that specific element.</p> + * <p>The additional parameter supplied to visitor methods may or + * may not be optional, and so the class is free to throw a + * {@code NullPointerException} if {@code null} is passed as the + * additional parameter.</p> + * <p>As this interface may be extended to accomodate future language + * versions, implementators are encouraged to extend one of the + * appropriate abstract classes rather than implementating this + * interface. However, this interface should be used as the type + * for parameters and return values.</p> + * + * @param <R> the return type of the visitor's methods. {@code Void} + * can be used where there is no return value. + * @param <P> the type of the additional parameter supplied to the visitor's + * methods. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface ElementVisitor<R,P> +{ + + /** + * A convenience method for use when there is no additional + * parameter to pass. This is equivalent to {@code #visit(element, null)}. + * + * @param element the element to visit. + * @return the return value specific to the visitor. + */ + R visit(Element element); + + /** + * Visits an element. + * + * @param element the element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visit(Element element, P param); + + /** + * Visits a type element. + * + * @param element the type element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitType(TypeElement element, P param); + + /** + * Visits an unknown element. This method is called if + * a new type of element is added to the hierarchy + * which isn't yet handled by the visitor. + * + * @param element the element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + * @throws UnknownElementException if the implementation chooses to. + */ + R visitUnknown(Element element, P param); + + /** + * Visits an executable element. + * + * @param element the executable element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitExecutable(ExecutableElement element, P param); + + /** + * Visits a type parameter element. + * + * @param element the type parameter element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitTypeParameter(TypeParameterElement element, P param); + + /** + * Visits a variable element. + * + * @param element the variable element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitVariable(VariableElement element, P param); + + /** + * Visits a package element. + * + * @param element the package element to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visitPackage(PackageElement element, P param); + +} diff --git a/javax/lang/model/element/ExecutableElement.java b/javax/lang/model/element/ExecutableElement.java new file mode 100644 index 000000000..389eff07e --- /dev/null +++ b/javax/lang/model/element/ExecutableElement.java @@ -0,0 +1,113 @@ +/* ExecutableElement.java -- Represents a method, constructor or initialiser. + 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.lang.model.element; + +import java.util.List; + +import javax.lang.model.type.TypeMirror; + +/** + * Represents a method, constructor or initialiser (static + * or instance) for a class or interface (including annotation + * types). + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.type.ExecutableType + */ +public interface ExecutableElement + extends Element +{ + + /** + * Returns the default value of this type if this is an + * annotation with a default, or {@code null} otherwise. + * + * @return the default value or {@code null}. + */ + AnnotationValue getDefaultValue(); + + /** + * Returns the formal parameters of this executable + * in the order they were declared. If there are no + * parameters, the list is empty. + * + * @return the formal parameters. + */ + List<? extends VariableElement> getParameters(); + + /** + * Returns the return type of this executable or + * an instance of {@link javax.lang.model.type.NoType} + * with the kind {@link javax.lang.model.type.TypeKind#VOID} + * if there is no return type or this is a + * constructor or initialiser. + * + * @return the return type of the executbale. + */ + TypeMirror getReturnType(); + + /** + * Returns the exceptions or other throwables listed + * in the {@code throws} clause in the order they + * are declared. The list is empty if there is no + * {@code throws} clause. + * + * @return the exceptions or other throwables listed + * as thrown by this executable. + */ + List<? extends TypeMirror> getThrownTypes(); + + /** + * Returns the formal type parameters of this executable + * in the order they were declared. The list is empty + * if there are no type parameters. + * + * @return the formal type parameters. + */ + List<? extends TypeParameterElement> getTypeParameters(); + + /** + * Returns {@code true} if this method or constructor accepts + * a variable number of arguments. + * + * @return true if this is a varargs method or constructor. + */ + boolean isVarArgs(); + +} diff --git a/javax/lang/model/element/Modifier.java b/javax/lang/model/element/Modifier.java new file mode 100644 index 000000000..20da02364 --- /dev/null +++ b/javax/lang/model/element/Modifier.java @@ -0,0 +1,71 @@ +/* Modifier.java -- Represents a modifier on an element such as a method. + 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.lang.model.element; + +/** + * Represents a modifier on an element such as a class, method + * or field. Not all modifiers are applicable to all elements. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum Modifier +{ + /** Denotes an abstract class or method. */ + ABSTRACT, + /** Denotes a final class, method or field. */ + FINAL, + /** Denotes a native method. */ + NATIVE, + /** Denotes a private class, method or field. */ + PRIVATE, + /** Denotes a protected class, method or field. */ + PROTECTED, + /** Denotes a public class, method or field. */ + PUBLIC, + /** Denotes a static class, method or field. */ + STATIC, + /** Denotes a strictfp class or method. */ + STRICTFP, + /** Denotes a synchronized method. */ + SYNCHRONIZED, + /** Denotes a transient field. */ + TRANSIENT, + /** Denotes a volatile field. */ + VOLATILE; +} diff --git a/javax/lang/model/element/Name.java b/javax/lang/model/element/Name.java new file mode 100644 index 000000000..28da2cab6 --- /dev/null +++ b/javax/lang/model/element/Name.java @@ -0,0 +1,90 @@ +/* Name.java -- An immutable sequence of characters. + 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.lang.model.element; + +/** + * <p>An immutable sequence of characters, representing a name. + * An empty name has a length of zero.</p> + * <p>Names created by the same implementation are comparable + * using {@link #equals(Object)} and thus usable in a collection. + * This guarantee as regards the "same implementation" also + * applies to successive annotation rounds in the context of + * annotation processing.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.util.Elements#getName(CharSequence) + */ +public interface Name + extends CharSequence +{ + + /** + * Returns true if the sequence of characters within this + * name is the same as the specified sequence of characters. + * + * @param chars the sequence of characters to compare. + * @return true if {@code chars} represents the same sequence + * of characters as this name. + * @see String#contentEquals(CharSequence) + */ + boolean contentEquals(CharSequence chars); + + /** + * Returns {@code true} if the specified object represents the + * same name as this instance. Name comparisons are not + * just reliant on the content of the name (see + * {@link #contentEquals(CharSequence)}) but also + * the implementation which created the name. + * + * @param obj the object to compare. + * @return {@code true} if {@code this} and {@code obj} represent + * the same element. + */ + boolean equals(Object obj); + + /** + * Obeys the general contract of {@link java.lang.Object#hashCode()}. + * + * @return a hash code for this element. + * @see #equals(Object) + */ + int hashCode(); + +} + diff --git a/javax/lang/model/element/NestingKind.java b/javax/lang/model/element/NestingKind.java new file mode 100644 index 000000000..d98e4d993 --- /dev/null +++ b/javax/lang/model/element/NestingKind.java @@ -0,0 +1,65 @@ +/* NestingKind.java -- Represents the nesting level of an element. + 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.lang.model.element; + +/** + * Represents the level of nesting at which an element appears; + * top-level, member, local and anonymous. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum NestingKind +{ + ANONYMOUS, + LOCAL, + MEMBER, + TOP_LEVEL; + + /** + * Returns true if this constant represents an element + * that is nested inside another i.e. is not top-level. + * + * @return true if this is a constant for a nested level. + */ + public boolean isNested() + { + return this != TOP_LEVEL; + } + +} diff --git a/javax/lang/model/element/PackageElement.java b/javax/lang/model/element/PackageElement.java new file mode 100644 index 000000000..71a06bc94 --- /dev/null +++ b/javax/lang/model/element/PackageElement.java @@ -0,0 +1,72 @@ +/* PackageElement.java -- Represents a package. + 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.lang.model.element; + +/** + * Represents a package, providing access to information about + * it and its members. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.util.Elements#getPackageOf(Element) + */ +public interface PackageElement + extends Element +{ + + /** + * Returns the fully qualified name (<emph>canonical + * name</emph>) of the package, as specified in section + * 6.7 of the Java Language Specification, or an empty + * name if the package is unnamed. + * + * @return the fully qualified name of the package. + * @see #isUnnamed() + */ + Name getQualifiedName(); + + /** + * Returns {@code true} if this is an unnamed package. + * Unnamed packages are detailed in section 7.4.2 of + * the Java Language Specification. + * + * @return true if this is an unnamed package. + */ + boolean isUnnamed(); + +} diff --git a/javax/lang/model/element/TypeElement.java b/javax/lang/model/element/TypeElement.java new file mode 100644 index 000000000..2e028fe40 --- /dev/null +++ b/javax/lang/model/element/TypeElement.java @@ -0,0 +1,126 @@ +/* TypeElement.java -- Represents a class or interface element. + 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.lang.model.element; + +import java.util.List; + +import javax.lang.model.type.TypeMirror; + +/** + * <p>Represents a class or interface program element. + * Note that enumerations are a kind of class and annotations + * are a kind of interface. The element provides access + * to information about the type and its members.</p> + * <p>A distinction is made between elements and types, + * with the latter being an invocation of the former. + * This distinction is most clear when looking at + * parameterized types. A {@code TypeElement} represents the + * general type, such as {@code java.util.Set}, while + * a {@link DeclaredType} instance represents different + * instantiations such as {@code java.util.Set<String>}, + * {@code java.util.Set<Integer>} and the raw type + * {@code java.util.Set}.</p> + * <p>The methods of this interface return elements in the + * natural order of the underlying information. So, for + * example, if the element is derived from a Java source + * file, elements are returned in the order they appear + * in the source code.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface TypeElement + extends Element +{ + + /** + * Returns the interface types directly implemented by this + * class or extended by this interface. If there are none, + * an empty list is returned. + * + * @return the interface types directly implemented by this + * class or extended by this interface. + */ + List<? extends TypeMirror> getInterfaces(); + + /** + * Returns the direct superclass of this element. If this + * is an interface or the class {@link Object}, then a + * instance of {@link javax.lang.model.type.NoType} with + * the kind {@link javax.lang.model.type.TypeKind#NONE} is + * returned. + * + * @return the direct superclass or {@code NoType} if there + * isn't one. + */ + TypeMirror getSuperclass(); + + /** + * Returns the formal type parameters of this element in the + * order they were declared. If there are none, then an empty + * list is returned. + * + * @return the formal type parameters. + */ + List<? extends TypeParameterElement> getTypeParameters(); + + /** + * Returns the fully qualified or <emph>canonical</emph> + * name of this type element. For a local or anonymous + * class, the empty string is returned. Generic types + * do not include their type parameters in the returned + * string i.e. {@code "java.util.Set"} not + * {@code "java.util.Set<E>"}. A period ({@code "."}) is + * the only separator used, including for nested classes + * such as {@code "java.util.Map.Entry"}. See + * Section 6.7 of the Java Language Specification for + * more details. + * + * @return the canonical name of this type element. + * @see javax.lang.model.util.Elements#getBinaryName(TypeElement) + */ + Name getQualifiedName(); + + /** + * Returns the nesting kind of this element. + * + * @return the nesting kind. + */ + NestingKind getNestingKind(); + +} diff --git a/javax/lang/model/element/TypeParameterElement.java b/javax/lang/model/element/TypeParameterElement.java new file mode 100644 index 000000000..fa5fb7424 --- /dev/null +++ b/javax/lang/model/element/TypeParameterElement.java @@ -0,0 +1,82 @@ +/* TypeParameterElement.java -- Represents a formal type parameter. + 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.lang.model.element; + +import java.util.List; + +import javax.lang.model.type.TypeMirror; + +/** + * Represents a formal type parameter used by a generic class, + * interface, method or constructor element. A type parameter + * is a declaration of a {@link javax.lang.model.type.TypeVariable}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.type.TypeVariable + */ +public interface TypeParameterElement + extends Element +{ + + /** + * Returns the bounds of the type parameter. These are the types + * declared after the {@code extends} clause. For example, + * the bounds for the type parameter {@code T} in + * {@code Set<T extends Integer>} would be a single element + * list containing the type mirror for {@code Integer}. Similarly, + * for {@code Set<T extends Number & Runnable>}, the bounds + * would be a two element list containing the type mirrors + * for {@code Number} and {@code Runnable}. For a parameter + * with no explicit bounds, {@code Object} is assumed to be + * the sole bound and an empty list is returned. + * + * @return the bounds of this type parameter, or an empty list if + * there are none. + */ + List<? extends TypeMirror> getBounds(); + + /** + * Returns the generic class, interface, method or constructor + * in which this type parameter is used. + * + * @return the element parameterised by this type parameter. + */ + Element getGenericElement(); + +} diff --git a/javax/lang/model/element/UnknownAnnotationValueException.java b/javax/lang/model/element/UnknownAnnotationValueException.java new file mode 100644 index 000000000..dd9056b5a --- /dev/null +++ b/javax/lang/model/element/UnknownAnnotationValueException.java @@ -0,0 +1,106 @@ +/* UnknownAnnotationValueException.java -- Thrown by an unknown annotation value. + 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.lang.model.element; + +/** + * Thrown when an unknown annotation value is encountered, + * usually by a {@link AnnotationValueVisitor}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see AnnotationValueVisitor#visitUnknown(AnnotationValue,P) + */ +public class UnknownAnnotationValueException + extends RuntimeException +{ + + private static final long serialVersionUID = 269L; + + /** + * The unknown annotation value. + */ + private AnnotationValue annValue; + + /** + * The additional parameter. + */ + private Object param; + + /** + * Constructs a new {@code UnknownAnnotationValueException} + * for the specified annotation value. An additional + * object may also be passed to give further context as + * to where the exception occurred, such as the additional parameter + * used by visitor classes. + * + * @param annValue the unknown annotation value or {@code null}. + * @param param the additional parameter or {@code null}. + */ + public UnknownAnnotationValueException(AnnotationValue annValue, + Object param) + { + this.annValue = annValue; + this.param = param; + } + + /** + * Returns the additional parameter or {@code null} if + * unavailable. + * + * @return the additional parameter. + */ + public Object getArgument() + { + return param; + } + + /** + * Returns the unknown annotation value or {@code null} + * if unavailable. The value may be {@code null} if + * the value is not {@link java.io.Serializable} but the + * exception has been serialized and read back in. + * + * @return the unknown annotation value. + */ + public AnnotationValue getUnknownAnnotationValue() + { + return annValue; + } + + +} diff --git a/javax/lang/model/element/UnknownElementException.java b/javax/lang/model/element/UnknownElementException.java new file mode 100644 index 000000000..cdf5f1877 --- /dev/null +++ b/javax/lang/model/element/UnknownElementException.java @@ -0,0 +1,105 @@ +/* UnknownElementException.java -- Thrown by an unknown element. + 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.lang.model.element; + +/** + * Thrown when an unknown element is encountered, + * usually by a {@link ElementVisitor}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see ElementVisitor#visitUnknown(Element,P) + */ +public class UnknownElementException + extends RuntimeException +{ + + private static final long serialVersionUID = 269L; + + /** + * The unknown element. + */ + private Element element; + + /** + * The additional parameter. + */ + private Object param; + + /** + * Constructs a new {@code UnknownElementException} + * for the specified element. An additional + * object may also be passed to give further context as + * to where the exception occurred, such as the additional parameter + * used by visitor classes. + * + * @param element the unknown element or {@code null}. + * @param param the additional parameter or {@code null}. + */ + public UnknownElementException(Element element, Object param) + { + this.element = element; + this.param = param; + } + + /** + * Returns the additional parameter or {@code null} if + * unavailable. + * + * @return the additional parameter. + */ + public Object getArgument() + { + return param; + } + + /** + * Returns the unknown element or {@code null} + * if unavailable. The element may be {@code null} if + * the value is not {@link java.io.Serializable} but the + * exception has been serialized and read back in. + * + * @return the unknown element. + */ + public Element getUnknownElement() + { + return element; + } + + +} diff --git a/javax/lang/model/element/VariableElement.java b/javax/lang/model/element/VariableElement.java new file mode 100644 index 000000000..2ff817f15 --- /dev/null +++ b/javax/lang/model/element/VariableElement.java @@ -0,0 +1,63 @@ +/* VariableElement.java -- Represents a field, enum constant, parameter or variable. + 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.lang.model.element; + +/** + * Represents a field, enumeration constant, local variable or + * a method, constructor or exception parameter. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface VariableElement + extends Element +{ + + /** + * Returns the constant value of the field if it has one + * or {@code null} otherwise. To have a constant value, + * a field must be declared {@code final} and be of either + * a primitive type or of type {@code String}. Enumeration + * constants do not meet this criteria and are not compile-time + * constants. + * + * @return the constant value of this variable if applicable. + */ + Object getConstantValue(); + +} diff --git a/javax/lang/model/type/ArrayType.java b/javax/lang/model/type/ArrayType.java new file mode 100644 index 000000000..94538bccd --- /dev/null +++ b/javax/lang/model/type/ArrayType.java @@ -0,0 +1,59 @@ +/* ArrayType.java -- Represents an array type. + 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.lang.model.type; + +/** + * Represents an array type. Multidimensional arrays are + * represented as array types where the component type + * is also an array type. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface ArrayType + extends ReferenceType +{ + + /** + * Returns the component type of the array. + * + * @return the component type. + */ + TypeMirror getComponentType(); + +} diff --git a/javax/lang/model/type/DeclaredType.java b/javax/lang/model/type/DeclaredType.java new file mode 100644 index 000000000..08efb82b3 --- /dev/null +++ b/javax/lang/model/type/DeclaredType.java @@ -0,0 +1,101 @@ +/* DeclaredType.java -- Represents a class or interface type. + 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.lang.model.type; + +import java.util.List; + +import javax.lang.model.element.Element; + +/** + * <p>Represents a type declared in the source code i.e. a class + * or an interface. This includes parameterised types, such + * as {@code Set<String>} as well as raw types, such as {@code Set}.</p> + * <p>A type represents the usage of a particular element and, as + * a result, multiple types can be represented by the same element. + * Both the {@code Set<String>} and {@code Set} types mentioned above + * would be represented by the same element.</p> + * <p>This interface is also used to represent <emph>intersection types</emph> + * which don't exist explicitly in the source code. For example, + * in {@code <T extends Number & Runnable>}, the bound is an intersection + * type. It is represented by a {@code DeclaredType} with {@code Number} + * as its superclass and {@code Runnable} as its single superinterface.</p> + * <p>To obtain the supertypes of a declared type, the method + * {@link javax.lang.model.util.Types#directSupertypes(TypeMirror)} should + * be used. This returns the superclass and any superinterfaces of the + * type with any type arguments substituted in.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.element.TypeElement + */ +public interface DeclaredType + extends ReferenceType +{ + + /** + * Returns the element which corresponds to this type. + * For example, the element for the type {@code Set<String>} + * would be the element for {@code Set}. + * + * @return the element corresponding to this type. + */ + Element asElement(); + + /** + * Returns the type of the innermost enclosing element or + * an instance of {@link NoType} with the kind {@link TypeKind#NONE} + * if this is a top-level type. Only types representing + * inner classes have enclosing instances. + * + * @return a type mirror for the enclosing type, if any. + */ + TypeMirror getEnclosingType(); + + /** + * Returns a list of the actual type arguments used by this + * type. For example, for {@code Set<String>}, the returned list + * would include a single type representing {@code String}. + * Only type arguments for this particular type are returned; type + * parameters for enclosing types are not included. If there are + * no type arguments, an empty list is returned. + * + * @return a list of the type arguments used by the type. + */ + List<? extends TypeMirror> getTypeArguments(); + +} diff --git a/javax/lang/model/type/ErrorType.java b/javax/lang/model/type/ErrorType.java new file mode 100644 index 000000000..34ac7a5e3 --- /dev/null +++ b/javax/lang/model/type/ErrorType.java @@ -0,0 +1,51 @@ +/* ErrorType.java -- Represents a type that can't be modelled. + 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.lang.model.type; + +/** + * Represents a type that can't be modelled. This may be as + * a result of a number of reasons, such as a missing class file, + * an erroneous source file or a processing error. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface ErrorType + extends DeclaredType +{ +} diff --git a/javax/lang/model/type/ExecutableType.java b/javax/lang/model/type/ExecutableType.java new file mode 100644 index 000000000..72d81b4b7 --- /dev/null +++ b/javax/lang/model/type/ExecutableType.java @@ -0,0 +1,98 @@ +/* ExecutableType.java -- Represents a method, constructor or initialiser. + 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.lang.model.type; + +import java.util.List; + +/** + * Represents something which may be executed i.e. a + * constructor, a method or an initialiser. The executable + * is viewed respective to a particular type. As a result, + * any type parameters will be substituted with actual type + * arguments as appropriate. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see + */ +public interface ExecutableType + extends TypeMirror +{ + + /** + * Returns the types of the formal parameters of this + * executable, or an empty list if the executable takes + * no parameters. For example, {@code doThis(int)} will + * return a list containing a single element, the type + * mirror for {@code int}. + * + * @return the executable's formal parameters. + */ + List<? extends TypeMirror> getParameterTypes(); + + /** + * Returns the return type of the executable. If the + * executable is a constructor or an initialiser, or + * does not return anything, this method will return + * an instance of {@link NoType} with the kind + * {@link TypeKind#VOID}. + * + * @return the return type of this executable. + */ + TypeMirror getReturnType(); + + /** + * Returns the types of any exceptions or other + * {@link Throwable}s mentioned in the {@code throws} + * clause of this executable, or an empty list if there + * are none. + * + * @return the exceptions and other throwables declared + * as thrown by this executable. + */ + List<? extends TypeMirror> getThrownTypes(); + + /** + * Returns the type variables declared by the formal type + * parameters or an empty list if there are none. + * + * @return the type variables declared by this executable. + */ + List<? extends TypeVariable> getTypeVariables(); + +} diff --git a/javax/lang/model/type/MirroredTypeException.java b/javax/lang/model/type/MirroredTypeException.java new file mode 100644 index 000000000..6c443ad58 --- /dev/null +++ b/javax/lang/model/type/MirroredTypeException.java @@ -0,0 +1,85 @@ +/* MirroredTypeException.java -- An attempt to access a TypeMirror's class. + 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.lang.model.type; + +/** + * Thrown when an application attempts to access the + * {@link Class} object corresponding to a {@link TypeMirror}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.element.Element#getAnnotation(Class) + */ +public class MirroredTypeException + extends RuntimeException +{ + + private static final long serialVersionUID = 269L; + + /** + * The type mirror. + */ + private TypeMirror mirror; + + /** + * Constructs a new {@code MirroredTypeException} + * for the specified type. + * + * @param mirror the mirrored type accessed. May be + * {@code null}. + */ + public MirroredTypeException(TypeMirror mirror) + { + this.mirror = mirror; + } + + /** + * Returns the type mirror or {@code null} + * if unavailable. The type mirror may be {@code null} if + * the type mirror is not {@link java.io.Serializable} but the + * exception has been serialized and read back in. + * + * @return the type mirror. + */ + public TypeMirror getTypeMirror() + { + return mirror; + } + + +} diff --git a/javax/lang/model/type/MirroredTypesException.java b/javax/lang/model/type/MirroredTypesException.java new file mode 100644 index 000000000..2014b6d0c --- /dev/null +++ b/javax/lang/model/type/MirroredTypesException.java @@ -0,0 +1,87 @@ +/* MirroredTypesException.java -- An attempt to access a series of TypeMirror classes. + 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.lang.model.type; + +import java.util.List; + +/** + * Thrown when an application attempts to access a sequence of + * {@link Class} objects, each corresponding to a {@link TypeMirror}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.element.Element#getAnnotation(Class) + */ +public class MirroredTypesException + extends RuntimeException +{ + + private static final long serialVersionUID = 269L; + + /** + * The type mirrors. + */ + private List<? extends TypeMirror> mirrors; + + /** + * Constructs a new {@code MirroredTypesException} + * for the specified types. + * + * @param mirrors the mirrored types accessed. May be + * {@code null}. + */ + public MirroredTypesException(List<? extends TypeMirror> mirrors) + { + this.mirrors = mirrors; + } + + /** + * Returns the type mirrors or {@code null} + * if unavailable. The list may be {@code null} if + * the type mirrors are not {@link java.io.Serializable} but the + * exception has been serialized and read back in. + * + * @return the type mirrors. + */ + public List<? extends TypeMirror> getTypeMirrors() + { + return mirrors; + } + + +} diff --git a/javax/lang/model/type/NoType.java b/javax/lang/model/type/NoType.java new file mode 100644 index 000000000..7cccc436a --- /dev/null +++ b/javax/lang/model/type/NoType.java @@ -0,0 +1,60 @@ +/* NoType.java -- Represents a pseudo-type used when nothing is appropriate. + 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.lang.model.type; + +/** + * <p>Represents a pseudo-type used when a {@link TypeMirror} + * needs to be returned, but there is not one suitable.</p> + * <p>Further information is provided by the kind of the + * instance, as follows:</p> + * <ul> + * <li>{@link TypeKind#VOID}; used for method return types.</li> + * <li>{@link TypeKind#PACKAGE}; used for packages.</li> + * <li>{@link TypeKind#NONE}: used when nothing else fits. + * For example, requesting a superclass from + * {@code java.lang.Object}.</li> + * </ul> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see javax.lang.model.element.ExecutableElement#getReturnType() + */ +public interface NoType + extends TypeMirror +{ +} diff --git a/javax/lang/model/type/NullType.java b/javax/lang/model/type/NullType.java new file mode 100644 index 000000000..53f9819bd --- /dev/null +++ b/javax/lang/model/type/NullType.java @@ -0,0 +1,50 @@ +/* NullType.java -- Represents the null type. + 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.lang.model.type; + +/** + * Represents the null type i.e. the type of the expression + * {@code null}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface NullType + extends ReferenceType +{ +} diff --git a/javax/lang/model/type/PrimitiveType.java b/javax/lang/model/type/PrimitiveType.java new file mode 100644 index 000000000..6586079df --- /dev/null +++ b/javax/lang/model/type/PrimitiveType.java @@ -0,0 +1,52 @@ +/* PrimitiveType.java -- Represents a primitive type. + 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.lang.model.type; + +/** + * Represents a primitive type such as a {@code byte}, + * {@code boolean}, {@code char}, {@code double}, + * {@code float}, {@code int}, {@code long} or + * {@code short}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface PrimitiveType + extends TypeMirror +{ +} diff --git a/javax/lang/model/type/ReferenceType.java b/javax/lang/model/type/ReferenceType.java new file mode 100644 index 000000000..174104ee9 --- /dev/null +++ b/javax/lang/model/type/ReferenceType.java @@ -0,0 +1,51 @@ +/* ReferenceType.java -- Represents a type referred to by reference. + 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.lang.model.type; + +/** + * Represents a type referred to by reference. This + * includes array types, class and interface types, + * type variables and the null type. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface ReferenceType + extends TypeMirror +{ +} diff --git a/javax/lang/model/type/TypeKind.java b/javax/lang/model/type/TypeKind.java new file mode 100644 index 000000000..37d2c9d5d --- /dev/null +++ b/javax/lang/model/type/TypeKind.java @@ -0,0 +1,112 @@ +/* TypeKind.java -- Represents the kind of a type. + 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.lang.model.type; + +/** + * Represents the kind of a type mirror, such as a boolean or + * a declared type. This enumeration may be extended with + * further kinds to represent future versions of the language. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum TypeKind +{ + /** An array type. */ + ARRAY, + /** The primitive type boolean */ + BOOLEAN, + /** The primitive type byte */ + BYTE, + /** The primitive type char */ + CHAR, + /** A class or interface type */ + DECLARED, + /** The primitive type double */ + DOUBLE, + /** An unresolvable type */ + ERROR, + /** A method, constructor or initialiser */ + EXECUTABLE, + /** The primitive type float */ + FLOAT, + /** The primitive type int */ + INT, + /** The primitive type long */ + LONG, + /** A pseudo-type used when nothing else is appropriate */ + NONE, + /** The null type */ + NULL, + /** An implementation-reserved type */ + OTHER, + /** A psuedo-type used for packages */ + PACKAGE, + /** The primitive type short */ + SHORT, + /** A type variable */ + TYPEVAR, + /** A psuedo-type used for the void return type. */ + VOID, + /** A wildcard type argument. */ + WILDCARD; + + /** + * Returns true if this is a primitive type. + * + * @return true if this is a primitive type. + */ + public boolean isPrimitive() + { + switch (this) + { + case BOOLEAN: + case BYTE: + case CHAR: + case DOUBLE: + case FLOAT: + case INT: + case LONG: + case SHORT: + return true; + default: + return false; + } + } + +} diff --git a/javax/lang/model/type/TypeMirror.java b/javax/lang/model/type/TypeMirror.java new file mode 100644 index 000000000..1c8397b94 --- /dev/null +++ b/javax/lang/model/type/TypeMirror.java @@ -0,0 +1,112 @@ +/* TypeMirror.java -- Represents a realised type. + 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.lang.model.type; + +/** + * <p> + * Represents a realised type in the Java programming language. For example, + * a {@code TypeMirror} may represent a primitive type, a declared type + * (classes and interfaces), an array type, a type variable or the + * {@code null} type. To complete the possible types, wildcard types + * are represented as is a pseudo-type to represent packages and + * {@code void}, and the signature and return types of executables + * (constructors, methods and initialisers). + * </p> + * <p>To compare two instances, use the utility methods in + * {@link javax.lang.model.util.Types} as there + * is no guarantee that == will hold. To determine the subtype of + * {@code TypeMirror}, use {@link #getKind()} or a visitor, as + * implementations may use the same class to implement multiple + * subinterfaces.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface TypeMirror +{ + + /** + * Applies a visitor to this type. + * + * @param <R> the return type of the visitor's methods. + * @param <P> the type of the additional parameter used in the visitor's + * methods. + * @param visitor the visitor to apply to the element. + * @param param the additional parameter to be sent to the visitor. + * @return the return value from the visitor. + */ + <R,P> R accept(TypeVisitor<R,P> visitor, P param); + + /** + * Obeys the general contract specified by {@link #equals(Object)} + * but does not indicate that two types represent the same type. + * For this, {@link javax.lang.model.Types#isSameType(TypeMirror, + * TypeMirror)} should be used and the result of this method and + * that method may differ. + * + * @param obj the object to compare. + * @return {@code true} if {@code this} and {@code obj} are equal. + */ + boolean equals(Object obj); + + /** + * Returns the kind of this element. + * + * @return the kind of element. + */ + TypeKind getKind(); + + /** + * Obeys the general contract of {@link java.lang.Object#hashCode()}. + * + * @return a hash code for this element. + * @see #equals(Object) + */ + int hashCode(); + + /** + * Returns an informative representation of the type. If possible, + * the form used should be the same as that used if the type was + * to be represented in source code. Any type names embedded in the + * result should be qualified where possible. + * + * @return a textual representation of the type. + */ + String toString(); + +} diff --git a/javax/lang/model/type/TypeVariable.java b/javax/lang/model/type/TypeVariable.java new file mode 100644 index 000000000..87b308780 --- /dev/null +++ b/javax/lang/model/type/TypeVariable.java @@ -0,0 +1,87 @@ +/* TypeVariable.java -- Represents a type variable. + 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.lang.model.type; + +import javax.lang.model.element.Element; + +/** + * Represents a type variable. Such variables may be the + * result of an explicitly declared type parameter on + * a type, method or constructor, or be created implicitly + * as a function of capture conversion on a wildcard type + * argument. See chapter 5 of the Java Language Specification. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface TypeVariable + extends ReferenceType +{ + + /** + * Returns the element which corresponds to this type variable. + * + * @return the element corresponding to this type variable. + */ + Element asElement(); + + /** + * Returns the lower bound of this type variable. While type + * variables can not be given an explicit lower bound, a + * non-trivial lower bound may be produced through capture + * conversion on a wildcard type argument. If this is not the + * case, the lower bound will be the {@link NullType}. + * + * @return the lower bound of this type variable. + */ + TypeMirror getLowerBound(); + + /** + * Returns the upper bound of this type variable. If an + * explicit upper bound was not given, this will return + * {@code java.lang.Object}. Where multiple upper bounds + * are specified, an intersection type is generated and + * represented as an instance of {@link DeclaredType}. + * The supertypes of this may be examined to find the + * actual bounds specified. + * + * @return the upper bound of this type variable. + */ + TypeMirror getUpperBound(); + +} diff --git a/javax/lang/model/type/TypeVisitor.java b/javax/lang/model/type/TypeVisitor.java new file mode 100644 index 000000000..3d2a327da --- /dev/null +++ b/javax/lang/model/type/TypeVisitor.java @@ -0,0 +1,188 @@ +/* TypeVisitor.java -- A visitor of types. + 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.lang.model.type; + +/** + * <p>A visitor for types. This is used when the specific + * type is not known at compile time. A visitor instance + * is passed to the {@link TypeMirror#accept(TypeVisitor,P)} method of + * the type, which then calls the specific {@code visitN} method + * appropriate to that specific type.</p> + * <p>The additional parameter supplied to visitor methods may or + * may not be optional, and so the class is free to throw a + * {@code NullPointerException} if {@code null} is passed as the + * additional parameter.</p> + * <p>As this interface may be extended to accomodate future language + * versions, implementators are encouraged to extend one of the + * appropriate abstract classes rather than implementating this + * interface. However, this interface should be used as the type + * for parameters and return values.</p> + * + * @param <R> the return type of the visitor's methods. {@code Void} + * can be used where there is no return value. + * @param <P> the type of the additional parameter supplied to the visitor's + * methods. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface TypeVisitor<R,P> +{ + + /** + * A convenience method for use when there is no additional + * parameter to pass. This is equivalent to {@code #visit(type, null)}. + * + * @param type the type to visit. + * @return the return value specific to the visitor. + */ + R visit(TypeMirror type); + + /** + * Visits a type. + * + * @param type the type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + */ + R visit(TypeMirror type, P param); + + /** + * Visits an unknown type. This method is called if + * a new type is added to the hierarchy which isn't yet + * handled by the visitor. + * + * @param type the type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + * @throws UnknownTypeException if the implementation chooses to. + */ + R visitUnknown(TypeMirror type, P param); + + /** + * Visits a declared type. + * + * @param type the type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitDeclared(DeclaredType type, P param); + + /** + * Visits an array type. + * + * @param type the array type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitArray(ArrayType type, P param); + + /** + * Visits an error type. + * + * @param type the error type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitError(ErrorType type, P param); + + /** + * Visits an executable type. + * + * @param type the executable type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitExecutable(ExecutableType type, P param); + + /** + * Visits a {@link NoType} instance. + * + * @param type the instance to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitNoType(NoType type, P param); + + /** + * Visits the null type. + * + * @param type the type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitNull(NullType type, P param); + + /** + * Visits a primitive type. + * + * @param type the primitive type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitPrimitive(PrimitiveType type, P param); + + /** + * Visits a type variable. + * + * @param type the type variable to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitTypeVariable(TypeVariable type, P param); + + /** + * Visits a wildcard type. + * + * @param type the wildcard type to visit. + * @param param the additional parameter, specific to the visitor. + * May be {@code null} if permitted by the visitor. + * @return the return value specific to the visitor. + */ + R visitWildcard(WildcardType type, P param); + +} diff --git a/javax/lang/model/type/UnknownTypeException.java b/javax/lang/model/type/UnknownTypeException.java new file mode 100644 index 000000000..063e3a750 --- /dev/null +++ b/javax/lang/model/type/UnknownTypeException.java @@ -0,0 +1,105 @@ +/* UnknownTypeException.java -- Thrown by an unknown type. + 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.lang.model.type; + +/** + * Thrown when an unknown type is encountered, + * usually by a {@link TypeVisitor}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + * @see TypeVisitor#visitUnknown(TypeMirror,P) + */ +public class UnknownTypeException + extends RuntimeException +{ + + private static final long serialVersionUID = 269L; + + /** + * The unknown type. + */ + private TypeMirror type; + + /** + * The additional parameter. + */ + private Object param; + + /** + * Constructs a new {@code UnknownTypeException} + * for the specified type. An additional + * object may also be passed to give further context as + * to where the exception occurred, such as the additional parameter + * used by visitor classes. + * + * @param type the unknown type or {@code null}. + * @param param the additional parameter or {@code null}. + */ + public UnknownTypeException(TypeMirror type, Object param) + { + this.type = type; + this.param = param; + } + + /** + * Returns the additional parameter or {@code null} if + * unavailable. + * + * @return the additional parameter. + */ + public Object getArgument() + { + return param; + } + + /** + * Returns the unknown type or {@code null} + * if unavailable. The type may be {@code null} if + * the value is not {@link java.io.Serializable} but the + * exception has been serialized and read back in. + * + * @return the unknown type. + */ + public TypeMirror getUnknownType() + { + return type; + } + + +} diff --git a/javax/lang/model/type/WildcardType.java b/javax/lang/model/type/WildcardType.java new file mode 100644 index 000000000..20dfd827a --- /dev/null +++ b/javax/lang/model/type/WildcardType.java @@ -0,0 +1,79 @@ +/* WildcardType.java -- Represents a wildcard type argument. + 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.lang.model.type; + +import javax.lang.model.element.Element; + +/** + * <p>Represents a wildcard type argument, which may take one + * of three forms:</p> + * <ul> + * <li>{@code ?}</li> + * <li>{@code ? extends X}</li> + * <li>{@code ? super Y}</li> + * </ul> + * <p>i.e. it may have no bounds, an upper bound set by + * the {@code extends} clause or a lower bound set by + * the {@code super} clause, but not both.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface WildcardType + extends TypeMirror +{ + + /** + * Returns the upper bound of this wildcard type, + * as declared by the {@code extends} clause, or + * {@code null} if one wasn't specified. + * + * @return the upper bound. + */ + TypeMirror getExtendsBound(); + + /** + * Returns the lower bound of this wildcard type, + * as declared by the {@code super} clause, or + * {@code null} if one wasn't specified. + * + * @return the upper bound. + */ + TypeMirror getSuperBound(); + +} diff --git a/javax/lang/model/util/ElementFilter.java b/javax/lang/model/util/ElementFilter.java new file mode 100644 index 000000000..9ddff2c65 --- /dev/null +++ b/javax/lang/model/util/ElementFilter.java @@ -0,0 +1,526 @@ +/* ElementFilter.java -- Filter for a collection of elements. + 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.lang.model.util; + +import java.util.Arrays; +import java.util.Collection; +import java.util.Iterator; +import java.util.NoSuchElementException; +import java.util.Set; + +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; + +/** + * <p>Filter for selecting elements of interest from a collection. + * The returned collections are new instances, but use the original + * collection as a backing store. They are not safe for concurrent + * access. The iteration order remains the same. Null values are + * not allowed and will throw a {@code NullPointerException}.</p> + *<p>For convenience, a static import may be used to allow the + * methods to be called more succinctly.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public class ElementFilter +{ + + /** + * Returns a set containing just the {@link TypeElement}s + * held in {@code elements}. + * + * @param elements the elements to filter. + * @return the filtered set. + */ + public static Set<TypeElement> typesIn(Set<? extends Element> elements) + { + return new FilteredSet<TypeElement>(elements, ElementKind.CLASS, + ElementKind.INTERFACE, + ElementKind.ENUM, + ElementKind.ANNOTATION_TYPE); + } + + /** + * Returns a set containing just the constructors + * held in {@code elements}. + * + * @param elements the elements to filter. + * @return the filtered set. + */ + public static Set<ExecutableElement> constructorsIn(Set<? extends Element> elements) + { + return new FilteredSet<ExecutableElement>(elements, ElementKind.CONSTRUCTOR); + } + + /** + * Returns a set containing just the fields + * held in {@code elements}. + * + * @param elements the elements to filter. + * @return the filtered set. + */ + public static Set<VariableElement> fieldsIn(Set<? extends Element> elements) + { + return new FilteredSet<VariableElement>(elements, ElementKind.FIELD, + ElementKind.ENUM_CONSTANT); + } + + /** + * Returns a set containing just the methods + * held in {@code elements}. + * + * @param elements the elements to filter. + * @return the filtered set. + */ + public static Set<ExecutableElement> methodsIn(Set<? extends Element> elements) + { + return new FilteredSet<ExecutableElement>(elements, ElementKind.METHOD); + } + + /** + * Returns a set containing just the packages + * held in {@code elements}. + * + * @param elements the elements to filter. + * @return the filtered set. + */ + public static Set<PackageElement> packagesIn(Set<? extends Element> elements) + { + return new FilteredSet<PackageElement>(elements, ElementKind.PACKAGE); + } + + /** + * Provides a filtered view of the given set, returning only + * instances which are of one of the specified kinds. + */ + private static final class FilteredSet<E extends Element> implements Set<E> + { + + /** + * The set being filtered. + */ + private Set<Element> elements; + + /** + * The kinds accepted by this filter. + */ + private ElementKind[] kinds; + + /** + * Constructs a new filtered set, returning + * only instances of {@code clazz} from + * {@code elements}. + * + * @param elements the set to filter. + * @param kinds the kinds to accept + * @throws NullPointerException if the set contains a null element. + */ + @SuppressWarnings("unchecked") + public FilteredSet(Set<? extends Element> elements, ElementKind... kinds) + { + this.elements = (Set<Element>) elements; + this.kinds = kinds; + Arrays.sort(kinds); + for (Element e : elements) + if (e == null) + throw new NullPointerException("Sets can not contain null values."); + } + + /** + * Adds an element to the set by passing it to the backing set. + * + * @param elem the element to add. + * @return true if the element was added. + */ + @Override + public boolean add(E elem) + { + return elements.add(elem); + } + + /** + * Add all elements of the given collection, which aren't already + * present in this set, to this set. If the supplied collection + * is also a set, the resulting set is the union of the two. + * This call is passed to the backing set. + * + * @param coll the collection of elements to add. + * @return true if the set was modified. + */ + @Override + public boolean addAll(Collection<? extends E> coll) + { + return elements.addAll(coll); + } + + /** + * Removes all elements from the set. + */ + @Override + public void clear() + { + elements.clear(); + } + + /** + * Returns true if the element is an instance of one + * of the specified kinds and the backing set contains + * the given element. + * + * @param obj the object to check for. + * @return true if the backing set contains the element. + */ + @Override + public boolean contains(Object obj) + { + if (obj instanceof Element) + { + Element elem = (Element) obj; + if (Arrays.binarySearch(kinds, elem.getKind()) >= 0) + return elements.contains(obj); + } + return false; + } + + /** + * Returns true if the set contains all elements of the + * given collection. If the collection is also a set, + * a return value of {@code true} means that the given + * set is a subset of this set. + * + * @param coll the collection of elements to check. + * @return true if the set contains all elements in {@code coll}. + */ + @Override + public boolean containsAll(Collection<?> coll) + { + for (Object obj : coll) + if (!contains(obj)) + return false; + return true; + } + + /** + * Returns true if the specified object is also a set + * of the same size and every member of it is also contained + * in this set. + * + * @param obj the object to compare. + * @return true if the above requirements are met. + */ + @Override + public boolean equals(Object obj) + { + if (obj == null) + return false; + if (obj instanceof Set) + { + Set<?> otherSet = (Set<?>) obj; + return size() == otherSet.size() && + containsAll(otherSet); + } + return false; + } + + /** + * Returns the hashcode of the set. The hash code is computed + * by taking the sum of the hash codes of the objects in the set. + * + * @return the hashcode of this set. + */ + @Override + public int hashCode() + { + int sum = 0; + for (E elem : this) + sum += elem.hashCode(); + return sum; + } + + /** + * Returns true if the set contains no elements. + * + * @return true if the size is zero. + */ + @Override + public boolean isEmpty() + { + return size() == 0; + } + + /** + * Returns an iterator over the set's elements. + * + * @return the iterator. + */ + @Override + public Iterator<E> iterator() + { + return new FilteredIterator<E>(elements.iterator(), kinds); + } + + /** + * Removes an element from the set if present. + * + * @param obj the object to remove. + * @return true if the set contained the element. + */ + @Override + public boolean remove(Object obj) + { + if (contains(obj)) + return elements.remove(obj); + return false; + } + + /** + * Removes from the set all elements contained in the specified + * collection. If the collection is also a set, the resulting + * set is the asymmetric set difference of the two. + * + * @param coll the collection of elements to remove. + * @return true if the set changed. + */ + @Override + public boolean removeAll(Collection<?> coll) + { + boolean modified = false; + for (Object obj : coll) + if (remove(obj)) + modified = true; + return modified; + } + + /** + * Retains only the elements in this set which are also contained in + * the specified collection. If the collection is also a set, the + * resulting set is the intersection of the two. + * + * @param coll the collection of elements to remove. + * @return true if the set changed. + */ + @Override + public boolean retainAll(Collection<?> coll) + { + boolean modified = false; + for (E elem : this) + if (!coll.contains(elem)) + { + remove(elem); + modified = true; + } + return modified; + } + + /** + * Returns the size of this set. This is the size of the backing + * set, minus any elements which aren't of one of the specified + * kinds. + * + * @return the size of the set. + */ + @Override + public int size() + { + int count = 0; + for (Element elem : elements) + if (Arrays.binarySearch(kinds, elem.getKind()) >= 0) + ++count; + return count; + } + + /** + * Returns a new array containing all the elements in the set. + * Modifications to the array do not affect the set. + * + * @return an array of all elements in the set. + */ + @Override + public Object[] toArray() + { + int size = size(); + Object[] array = new Object[size]; + Iterator<E> iterator = iterator(); + for (int a = 0; a < size; ++a) + array[a] = iterator.next(); + return array; + } + + /** + * Returns a array containing all the elements in the set with + * the runtime type of the specified array. If all the elements + * from the set fit into the specified array, it will be used + * for the returned array and any remaining space will be + * populated with {@code null} values. Otherwise, a new array + * will be allocated. + * + * @param array the array which may be reused to provide the + * return value of this method. + * @return an array containing all elements in the set. + */ + @Override + public <T> T[] toArray(T[] array) + { + int a, size = size(); + Iterator<E> iterator = iterator(); + if (array.length < size) + { + @SuppressWarnings("unchecked") + T[] newArray = (T[]) new Object[size]; + array = newArray; + } + Object[] elemArray = (Object[]) array; + for (a = 0; a < size; ++a) + elemArray[a] = iterator.next(); + for (; a < array.length; ++a) + elemArray[a] = null; + return array; + } + + /** + * Returns a textual representation of the filtered set. + * + * @return a textual representation. + */ + @Override + public String toString() + { + StringBuilder builder = new StringBuilder("["); + for (E elem : this) + { + builder.append(elem.toString()); + builder.append(","); + } + builder.insert(builder.length() - 1, "]"); + return builder.toString(); + } + + } + + /** + * Provides a filtered view of the given iterator, returning only + * instances which are of one of the specified kinds. + */ + private static final class FilteredIterator<E extends Element> implements Iterator<E> + { + + /** + * The iterator to filter. + */ + private Iterator<Element> iterator; + + /** + * The kinds accepted by this filter. + */ + private ElementKind[] kinds; + + /** + * Holds the next object if we had to retrieve it + * in the {@link #hasNext()} method. + */ + private Element next; + + /** + * Constructs a new filtered iterator which only returns + * elements that are of one of the specified kinds. + * + * @param iterator the iterator to filter. + * @param kinds the kinds to accept. This is assumed + * to be sorted. + */ + public FilteredIterator(Iterator<Element> iterator, + ElementKind... kinds) + { + this.iterator = iterator; + this.kinds = kinds; + } + + /** + * Returns true if there are more elements to come. + * + * @return true if there are more elements to retrieve. + */ + @Override + public boolean hasNext() + { + while (iterator.hasNext() && next == null) + { + next = iterator.next(); + if (Arrays.binarySearch(kinds, next.getKind()) < 0) + next = null; + } + return next != null; + } + + /** + * Returns the next element in the iteration which is of + * one of the specified kinds. + * + * @return the next element. + */ + @Override + public E next() + { + if (next == null) + if (!hasNext()) + throw new NoSuchElementException("No more elements to return."); + // The kind check means it should be of the correct type. + @SuppressWarnings("unchecked") + E retVal = (E) next; + next = null; + return retVal; + } + + /** + * Removes the last element returned by the iterator. + * As we only return elements that match the filter, + * the underlying iterator will always remove one of those. + */ + @Override + public void remove() + { + iterator.remove(); + } + } +} + diff --git a/javax/lang/model/util/Elements.java b/javax/lang/model/util/Elements.java new file mode 100644 index 000000000..71ea95e39 --- /dev/null +++ b/javax/lang/model/util/Elements.java @@ -0,0 +1,244 @@ +/* Elements.java -- Utility methods for operating on elements. + 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.lang.model.util; + +import java.io.Writer; + +import java.util.List; +import java.util.Map; + +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.AnnotationValue; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.Name; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; + +/** + * Utility methods for operating on elements. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Elements +{ + + /** + * Returns all members of a type element, whether declared + * directly in that element or inherited. For a class element, + * this includes all constructors, but not local or anonymous + * classes. + * + * @param type the type to return the members of. + * @return all members of the type. + * @see Element#getEnclosedElements() + */ + List<? extends Element> getAllMembers(TypeElement type); + + /** + * Returns the text of a constant expression which represents + * either a primitive value or a {@link String}. The returned + * text is in a form suitable for inclusion in source code. + * + * @param value a primitive value or string. + * @return the text of the constant expression. + * @throws IllegalArgumentExpression if the argument is not a + * primitive value or string. + */ + String getConstantExpression(Object value); + + /** + * Returns the text of the documentation comment attached to + * an element. + * + * @param elem the element whose comment should be returned. + * @return the documentation comment, or {@code null} if there is none. + */ + String getDocComment(Element elem); + + /** + * Returns a type element, given its canonical name. + * + * @param name the canonical name of the element. + * @return the named type element or {@code null} if it wasn't found. + */ + TypeElement getTypeElement(CharSequence name); + + /** + * Tests whether a type, method or field hides another. + * + * @param hider the element that is doing the hiding. + * @param hidden the element hidden by the hider. + * @return true if, and only if, the hider hides the hidden element. + */ + boolean hides(Element hider, Element hidden); + + /** + * Returns true if the specified element has been deprecated. + * + * @param elem the element to check for deprecation. + * @return true if the element is deprecated. + */ + boolean isDeprecated(Element elem); + + /** + * Prints out a representation of the elements in the order specified + * using the supplied writer. The main purpose of this method is for + * debugging purposes and the format of the output is not defined. + * + * @param writer the writer to send the output to. + * @param elements the elements to print. + */ + void printElements(Writer w, Element... elements); + + /** + * Returns all annotations associated with this element, + * whether present directly or inherited. + * + * @param element the element to examine. + * @return the annotations associated with this element or + * an empty list if there are none. + * @see Element#getAnnotationMirrors() + */ + List<? extends AnnotationMirror> getAllAnnotationMirrors(Element element); + + /** + * Returns a map of elements to their values, including both + * those explicitly specified and default values. + * A marker annotation, by definition, returns an empty map. + * The order of the elements in the map follows that of the + * source code. + * + * @param annotation the annotation whose values should be returned. + * @return the map of elements to values. + */ + Map<? extends ExecutableElement, ? extends AnnotationValue> + getElementValuesWithDefaults(AnnotationMirror annotation); + + /** + * <p>Returns true if the method {@code overrider} overrides + * the method {@code overridden}, when {@code overrider} is + * a member of the given type, according to sections + * 8.4.8 and 9.4.1 of the Java Language Specification.</p> + * <p>In most cases, the specified type will simply be the + * class containing {@code overrider}. For example, when + * checking if {@code String.hashCode()} overrides + * {@code Object.hashCode()}, the type will be {@code String}. + * However, in a more complex situation, the overridden and + * the overrider methods may be members of distinct types, + * {@code A} and {@code B}. If the type refers to {@code B}, + * the result will be {@code false} as {@code B} has no + * relationship to the methods in {@code A}. However, if the + * type refers to a third type {@code C}, which forms the + * intersection of {@code A} and {@code B} (say, it extends + * the class {@code A} and implements the interface {@code B}), + * then the result may be true.</p> + * + * @param overrider the method which may overrider the other. + * @param overridden the method which may be overridden. + * @param type the type of which the overrider is a member. + * @return true if the overrider overriders the overridden + * method in the specified type. + */ + boolean overrides(ExecutableElement overrider, + ExecutableElement overridden, + TypeElement type); + + /** + * <p>Returns the <emph>binary name</emph> of a type element. + * This is determined as follows, according to section + * 13.1 of the Java Language Specification:</p> + * <ul> + * <li>The binary name of a top-level element is its canonical name + * e.g. {@code java.util.Set}.</li> + * <li>The binary name of a member type is the binary name of + * its immediate enclosing type followed by the simple name of the + * member, separated by a {@code $} e.g. {@code java.util.Map$Entry}.</li> + * <li>The binary name of a local class is the binary name of + * its immediate enclosing type followed by the simple name of the + * local class, separated by {@code $} and a non-empty sequence of + * digits e.g. {@code java.awt.Window$1DisposeAction}.</li> + * <li>The binary name of an anonymous class is the binary name of + * its immediate enclosing type followed by a non-empty sequence of + * digits, separated by {@code $} e.g. {@code java.io.Console$1}.</li> + * <li>the binary name of a type variable declared by a generic + * class or interface is the binary name of its immediate enclosing type + * followed by the simple name of the type variable, separated by + * {@code $} e.g. {@code java.util.Set$E}</li>. + * <li>the binary name of a type variable declared by a generic + * method or constructor is the binary name of the type declaring the method + * or constructor, then a {@code $}, folllowed by the method or constructor + * descriptor, another {@code $} and the simple name of the type variable e.g. + * {@code java.util.Set$(Ljava/lang/Object;)Z$E</li>. + * </ul> + * + * @param type the type whose binary name should be returned. + * @return the binary name, according to the above. + * @see javax.lang.model.util.element.TypeElement#getQualifiedName() + */ + Name getBinaryName(TypeElement type); + + /** + * Returns a name using the specified sequence of characters. + * + * @param chars the character sequence to use for the name. + * @return the resulting name. + */ + Name getName(CharSequence chars); + + /** + * Returns a package element corresponding to the specified + * package name, or {@code null} if it could not be found. + * + * @param chars the character sequence which makes up the name + * of the package, or {@code ""} for the unnamed package. + * @return a corresponding package element. + */ + PackageElement getPackageElement(CharSequence chars); + + /** + * Returns the package which contains the specified element. + * If the given element is itself a package, it is returned. + * + * @param element the element whose package should be returned. + * @return the package for the specified type. + */ + PackageElement getPackageOf(Element element); + +} diff --git a/javax/lang/model/util/Types.java b/javax/lang/model/util/Types.java new file mode 100644 index 000000000..86647d1b6 --- /dev/null +++ b/javax/lang/model/util/Types.java @@ -0,0 +1,331 @@ +/* Types.java -- Utility methods for operating on types. + 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.lang.model.util; + +import java.util.List; + +import javax.lang.model.element.Element; +import javax.lang.model.element.TypeElement; + +import javax.lang.model.type.ArrayType; +import javax.lang.model.type.DeclaredType; +import javax.lang.model.type.ExecutableType; +import javax.lang.model.type.NoType; +import javax.lang.model.type.NullType; +import javax.lang.model.type.PrimitiveType; +import javax.lang.model.type.TypeKind; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.type.WildcardType; + +/** + * Utility methods for operating on types. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Types +{ + + /** + * Returns the element corresponding to this type + * or {@code null} if no such element exists. + * The type may be a {@link javax.lang.model.type.DeclaredType} + * or a {@link javax.lang.model.type.TypeVariable}. + * + * @param type the type to return the corresponding element to. + * @return the element corresponding to this type. + */ + Element asElement(TypeMirror type); + + /** + * Returns a view of an element when seen as a member of, + * or otherwise contained by, the specified type. For + * example, the method {@code Set.add(E)} becomes + * {@code Set.add(String)} when viewed as a member of + * the parameterised type {@code Set<String>}. + * + * @param container the type containing the element. + * @param element the element being contained. + * @return the type of the element viewed from the container. + * @throws IllegalArgumentException if the element is not applicable + * for the specified container. + */ + TypeMirror asMemberOf(DeclaredType container, Element element); + + /** + * Applies capture conversion to the type, as specified + * in section 5.1.10 of the Java Language Specification. + * + * @param type the type to capture convert. + * @return the result of applying capture conversion. + * @throws IllegalArgumentException if given an executable or package type. + */ + TypeMirror capture(TypeMirror type); + + /** + * Returns {@code true} if {@code type1} contains {@code type2}. + * + * @param type1 the first type. + * @param type2 the second type. + * @return true if type1 contains type2. + * @throws IllegalArgumentException if given an executable or package type. + */ + boolean contains(TypeMirror type1, TypeMirror type2); + + /** + * Returns the direct supertypes of the specified type. The superclass + * appears first, if any, followed by the interfaces, if any. + * + * @param type the type to examine. + * @return the direct supertypes or an empty list if there are none. + * @throws IllegalArgumentException if given an executable or package type. + */ + List<? extends TypeMirror> directSupertypes(TypeMirror type); + + /** + * Returns the erasure of the type, as specified by section + * 4.6 of the Java Language Specification. + * + * @param type the type to erase. + * @return the type erasure. + * @throws IllegalArgumentException if given a package type. + */ + TypeMirror erasure(TypeMirror type); + + /** + * <p>Returns the type corresponding to a type element and actual + * type arguments, given the specified containing type of which + * it is a member. This method is needed to retrieve types + * contained by parameterised types, for example + * {@code Outer<String>.Inner<Integer>}. To obtain this type, + * this method should be supplied with the {@link DeclaredType} + * for {@code Outer<String>} (probably obtained by a call + * to {@link #getDeclaredType(TypeElement, TypeMirror...)}), + * the element representing {@code Inner} and the + * {@link TypeMirror} for {@code String}</p>. + * <p>If the container is parameterised, the number of type + * arguments must equal the number of formal type parameters + * used in the specified element. Calls where the container + * is not parameterised, or is {@code null}, are equivalent + * to calls to {@link #getDeclaredType(TypeElement, TypeMirror...)}. + * + * @param container the type containing the returned type, + * or {@code null} if there is none. + * @param element the type element to return the realised type for. + * @param args the actual type arguments to match to the element's + * formal parameters. + * @return the type corresponding to the specified element using + * the specified type arguments. + * @throws IllegalArgumentException if the number of type arguments + * doesn't match the number of type + * parameters, or an inappropriate + * container, type element or argument + * is given. + */ + DeclaredType getDeclaredType(DeclaredType container, TypeElement element, + TypeMirror... args); + + /** + * Returns the type corresponding to a type element and actual + * type arguments. So, for the type element for {@code Set<T>}, + * and the type mirror for {@code String}, this method would + * return the declared type for {@code Set<String>}. The number + * of type arguments must either match the number of formal + * type parameters in the element, or be zero in order to obtain + * the raw type ({@code Set} in the above). The type element + * must not be contained within a generic outer class; for that, + * use {@link #getDeclaredType(DeclaredType,TypeElement,TypeMirror...)}. + * + * @param element the type element to return the realised type for. + * @param args the actual type arguments to match to the element's + * formal parameters. + * @return the type corresponding to the specified element using + * the specified type arguments. + * @throws IllegalArgumentException if the number of type arguments + * doesn't match the number of type + * parameters, or an inappropriate + * type element or argument is given. + */ + DeclaredType getDeclaredType(TypeElement element, TypeMirror... args); + + /** + * Returns {@code true} if {@code type1} may be assigned to {@code type2}, + * according to section 5.2 of the Java Language Specification. + * + * @param type1 the first type. + * @param type2 the second type. + * @return true if type1 can be assigned to type2. + * @throws IllegalArgumentException if given an executable or package type. + */ + boolean isAssignable(TypeMirror type1, TypeMirror type2); + + /** + * Returns {@code true} if the two types are the same. Note that + * wildcard types are never the same as any other type, including + * themselves. This rule prevents wildcard types being used as + * method arguments. + * + * @param type1 the first type. + * @param type2 the second type. + * @return true iff the two types are the same. + */ + boolean isSameType(TypeMirror type1, TypeMirror type2); + + /** + * Returns {@code true} if {@code type1} is a subtype of {@code type2}, + * according to section 4.10 of the Java Language Specification. A + * type is always considered a subtype of itself. + * + * @param type1 the first type. + * @param type2 the second type. + * @return true if type1 is a subtype of type2. + * @throws IllegalArgumentException if given an executable or package type. + */ + boolean isSubtype(TypeMirror type1, TypeMirror type2); + + /** + * <p>Returns the class which is used to wrap the given primitive + * type, according to the following mapping given in section + * 5.1.7 of the Java Language Specification:</p> + * <ul> + * <li>{@code boolean} ==> {@code Boolean}</li> + * <li>{@code byte} ==> {@code Byte}</li> + * <li>{@code char} ==> {@code Character}</li> + * <li>{@code double} ==> {@code Double}</li> + * <li>{@code float} ==> {@code Float}</li> + * <li>{@code int} ==> {@code Integer}</li> + * <li>{@code long} ==> {@code Long}</li> + * <li>{@code short} ==> {@code Short}</li> + * </ul> + * + * @param primitive the primitive type whose wrapper class should + * be returned. + * @return the wrapper class used for the given primitive type. + */ + TypeElement boxedClass(PrimitiveType primitive); + + /** + * Returns an array type with the specified component type. + * + * @param componentType the component type to be used in the array. + * @return an array type using the specified component type. + * @throws IllegalArgumentException if the component type given + * can not be used in an array. + */ + ArrayType getArrayType(TypeMirror componentType); + + /** + * Returns a pseudo-type of the specified kind for use where a real + * type is not applicable. Only the kinds {@link TypeKind#VOID} + * and {@link TypeKind#NONE} should be passed to this method. + * For packages, use + * {@code Elements#getPackageElement(CharSequence).asType()} + * instead. + * + * @param kind the kind of {@link NoType} to return. + * @return the corresponding instance. + * @throws IllegalArgumentException if an invalid kind is given. + */ + NoType getNoType(TypeKind kind); + + /** + * Returns the null type i.e. the type of {@code null}. + * + * @return the null type. + */ + NullType getNullType(); + + /** + * Returns a primitive type of the given kind. + * + * @param kind the kind of primitive type to return. + * @return the corresponding instance. + * @throws IllegalArgumentException if the kind given is not + * a primitive type. + */ + PrimitiveType getPrimitiveType(TypeKind kind); + + /** + * Returns a wildcard type with the specified bounds. + * Each bound is optional and {@code null} may be passed + * instead. It is invalid for both bounds to be non-null. + * + * @param extendsBound the upper bound, which usually follows the + * {@code extends clause}, or {@code null}. + * @param superBound the lower bound, which usually follows the + * {@code super clause}, or {@code null}. + * @return the corresponding wildcard type. + * @throws IllegalArgumentException if the bounds are invalid. + */ + WildcardType getWildcardType(TypeMirror extendsBound, + TypeMirror superBound); + + /** + * Returns {@code true} if the signature of {@code method1} is + * a subsignature of the signature of {@code method2}, according + * to section 8.4.2 of the Java Language Specification. + * + * @param method1 the first method. + * @param method2 the second method. + * @return true if method1's signature is a subsignature of method2's. + */ + boolean isSubsignature(ExecutableType method1, ExecutableType method2); + + /** + * <p>Returns the primitive type which is used to unwrap the value + * contained in the specified wrapper class, according to the following + * mapping given in section 5.1.8 of the Java Language Specification:</p> + * <ul> + * <li>{@code Boolean} ==> {@code boolean}</li> + * <li>{@code Byte} ==> {@code byte}</li> + * <li>{@code Character} ==> {@code char}</li> + * <li>{@code Double} ==> {@code double}</li> + * <li>{@code Float} ==> {@code float}</li> + * <li>{@code Integer} ==> {@code int}</li> + * <li>{@code Long} ==> {@code long}</li> + * <li>{@code Short} ==> {@code short}</li> + * </ul> + * + * @param wrapper the wrapper class for which the corresponding primitive + * type should be returned. + * @return the corresponding primitive type. + * @throws IllegalArgumentException if the given class is not a wrapper class. + */ + PrimitiveType unboxedType(TypeMirror wrapper); + +} diff --git a/javax/tools/FileObject.java b/javax/tools/FileObject.java index e04c056c7..bde59eab3 100644 --- a/javax/tools/FileObject.java +++ b/javax/tools/FileObject.java @@ -1,4 +1,4 @@ -/* FileObject.java -- +/* FileObject.java -- File object abstraction. Copyright (C) 2008 Free Software Foundation, Inc. This file is part of GNU Classpath. diff --git a/javax/tools/ForwardingFileObject.java b/javax/tools/ForwardingFileObject.java new file mode 100644 index 000000000..20eb75e84 --- /dev/null +++ b/javax/tools/ForwardingFileObject.java @@ -0,0 +1,161 @@ +/* ForwardingFileObject.java -- File object that forwards to another. + 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.tools; + +import java.io.InputStream; +import java.io.IOException; +import java.io.OutputStream; +import java.io.Reader; +import java.io.Writer; + +import java.net.URI; + +/** + * Forwards calls to a specified file object. + * + * @param <F> the kind of object calls are forwarded to. + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public class ForwardingFileObject<F extends FileObject> + implements FileObject +{ + + /** + * The file object to delegate to. + */ + protected F fileObject; + + /** + * Creates a new forwarder, delegating calls to the + * specified object. + * + * @param obj the object to forward calls to. + */ + protected ForwardingFileObject(F obj) + { + fileObject = obj; + } + + /** + * @inheritDoc + */ + @Override + public boolean delete() + { + return fileObject.delete(); + } + + /** + * @inheritDoc + */ + @Override + public CharSequence getCharContent(boolean ignoreEncodingErrors) + throws IOException + { + return fileObject.getCharContent(ignoreEncodingErrors); + } + + /** + * @inheritDoc + */ + @Override + public long getLastModified() + { + return fileObject.getLastModified(); + } + + /** + * @inheritDoc + */ + @Override + public String getName() + { + return fileObject.getName(); + } + + /** + * @inheritDoc + */ + @Override + public InputStream openInputStream() + throws IOException + { + return fileObject.openInputStream(); + } + + /** + * @inheritDoc + */ + @Override + public OutputStream openOutputStream() + throws IOException + { + return fileObject.openOutputStream(); + } + + /** + * @inheritDoc + */ + @Override + public Reader openReader(boolean ignoreEncodingErrors) + throws IOException + { + return fileObject.openReader(ignoreEncodingErrors); + } + + /** + * @inheritDoc + */ + @Override + public Writer openWriter() + throws IOException + { + return fileObject.openWriter(); + } + + /** + * @inheritDoc + */ + @Override + public URI toUri() + { + return fileObject.toUri(); + } + +} diff --git a/javax/tools/ForwardingJavaFileObject.java b/javax/tools/ForwardingJavaFileObject.java new file mode 100644 index 000000000..2ed9cb359 --- /dev/null +++ b/javax/tools/ForwardingJavaFileObject.java @@ -0,0 +1,102 @@ +/* ForwardingJavaFileObject.java -- Java file object that forwards to another. + 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.tools; + +import javax.lang.model.element.Modifier; +import javax.lang.model.element.NestingKind; + +/** + * Forwards calls to a specified {@link JavaFileObject}. + * + * @param <F> the kind of object calls are forwarded to. + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public class ForwardingJavaFileObject<F extends JavaFileObject> + extends ForwardingFileObject<F> + implements JavaFileObject +{ + + /** + * Creates a new forwarder, delegating calls to the + * specified object. + * + * @param obj the object to forward calls to. + */ + protected ForwardingJavaFileObject(F obj) + { + super(obj); + } + + /** + * @inheritDoc + */ + @Override + public JavaFileObject.Kind getKind() + { + return ((JavaFileObject) fileObject).getKind(); + } + + /** + * @inheritDoc + */ + @Override + public boolean isNameCompatible(String simpleName, JavaFileObject.Kind kind) + { + return ((JavaFileObject) fileObject).isNameCompatible(simpleName, kind); + } + + /** + * @inheritDoc + */ + @Override + public Modifier getAccessLevel() + { + return ((JavaFileObject) fileObject).getAccessLevel(); + } + + /** + * @inheritDoc + */ + @Override + public NestingKind getNestingKind() + { + return ((JavaFileObject) fileObject).getNestingKind(); + } + +} diff --git a/javax/tools/JavaCompiler.java b/javax/tools/JavaCompiler.java new file mode 100644 index 000000000..e1a8430c4 --- /dev/null +++ b/javax/tools/JavaCompiler.java @@ -0,0 +1,213 @@ +/* JavaCompiler.java -- Programmatic interface for a compiler. + 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.tools; + +import java.io.Writer; + +import java.nio.charset.Charset; + +import java.util.Locale; + +import java.util.concurrent.Callable; + +import javax.annotation.processing.Processor; + +/** + * <p> + * Provides a programmatic interface to a compiler for the Java + * programming language. The compiler relies on two services; + * a diagnostic listener for producing textual output including + * warnings or errors from the code, and a file manager for providing + * access to the files to be compiled and the output location. + * More detail on these services and various helper classes related + * to them is provided below. The classes {@link DiagnosticListener}, + * {@link JavaFileManager}, {@link FileObject} and {@link JavaFileObject} + * provide the service provider interface for these services and are not + * intended for user consumption.</p> + * <p>Compilers implementing {@link JavaCompiler} must conform to the Java + * Language Specification and produce class files conforming to the + * Java Virtual Machine Specification. In addition, those compilers + * which claim to support {@link SourceVersion#RELEASE_6} or later + * must support annotation processing.</p> + * <h2>Diagnostics</h2> + * <p>Where possible, the compiler provides diagnostic output to + * a {@link DiagnosticListener} if provided. If a listener is + * not provided, diagnostics are instead written to the default + * output ({@code{System.err} by default). This may also happen + * where the diagnostics are inappropriate for a {@link Diagnostic} + * object. The class {@link DiagnosticCollector} provides a means + * collate together multiple {@link Diagnostic}s in a list.</p> + * <h2>The File Manager</h2> + * <p>A compiler tool has an associated standard file manager which + * is native to it. An instance of it can be obtained by calling + * {@link #getStandardFileManager(DiagnosticListener,Locale,Charset)} + * and this is automatically called if no file manager is supplied to + * the compiler. However, the compiler must work with other file + * managers, provided they meet the requirements detailed in the methods + * below. Such file managers allow the user to customise how the compiler + * reads and writes files, and can be shared between multiple compilation + * tasks. Such reuse between different tasks can potentially provide + * a performance improvement.</p> + * <p>The standard file manager returned by this interface is an instance + * of the subinterface, {@link StandardJavaFileManager}, which is intended + * for operating on regular files and provides additional methods to support + * this.</p> + * <p>All file managers return a {@link FileObject} which provides an + * abstraction from the underlying file. The class {@link SimpleJavaFileObject} + * is provided as a means to simplifying implementing this interface.</p> + * <h2>Forwarding</h2> + * <p>As file managers and file objects are provided as return values from + * the methods of {@link JavaCompiler} and the file manager respectively, + * there is no means to override their behaviour by subclassing. Instead, + * it is necessary to wrap the returned instance in another implementation + * and forward method calls to it as appropriate. The classes + * {@link ForwardingJavaFileManager}, {@link ForwardingFileObject} and + * {@link ForwardingJavaFileObject} facilitate this by providing an + * implementation that simply forwards to another, which can then be subclassed + * to provide additional behaviour.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface JavaCompiler + extends Tool, OptionChecker +{ + + /** + * Interface representing a compilation task as an asynchronous + * event or {@link java.util.concurrent.Future}. The task may be + * started by invoking {@link #call()}. Prior to this, the task + * may be configured by the user using the other methods of this + * interface. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ + public static interface CompilationTask + extends Callable<Boolean> + { + + /** + * Performs the compilation. The compilation may only + * be performed once. Subsequent calls will throw + * an {@link IllegalStateException}. + * + * @return true if all files were successfully compiled. + * @throws RuntimeException if an unrecoverable error occurred + * in a user-supplied component of + * the compilation process. The user + * exception will be provided as the + * cause of this exception. + * @throws IllegalStateException if the compilation has already run. + */ + Boolean call(); + + /** + * Sets the locale to use for outputting diagnostics. + * + * @param locale the locale to use. A value of {@code null} + * means no locale is applied. + * @throws IllegalStateException if the compilation has started. + */ + void setLocale(Locale locale); + + /** + * Explicitly set the annotation processors to be used, + * overriding the usual discovery process. + * + * @param processors the processors to use. + * @throws IllegalStateException if the compilation has started. + */ + void setProcessors(Iterable<? extends Processor> processors); + + } + + /** + * Returns a new instance of the standard file manager implementation + * used by this tool. Any non-fatal diagnostics produced by the tool + * will be passed to the specified {@link DiagnosticListener}, if + * supplied, using the given locale. Calls to the file manager after + * a {@link JavaFileManager#flush()} or {@link JavaFileManager#close()} + * will cause the file manager to be reopened. The file manager must + * be usable with other tools. + * + * @param listener the diagnostic listener to use or {@code null} if + * the compiler should use its own methods for producing + * diagnostics. + * @param locale the locale to use to format the diagnostics or {@code null} + * to use the default locale. + * @param charset the character set to use for decoding bytes or {@code null} + * to use the platform default. + * @return the standard file manager implementation. + */ + StandardJavaFileManager getStandardFileManager(DiagnosticListener<? super JavaFileObject> listener, + Locale locale, Charset charset); + + /** + * Returns an asynchrononous task for performing the specified compilation. + * The compilation may not have completed upon return of this method. + * If a file manager is specified, it must supported all locations specified + * in {@link StandardLocation}. + * + * @param out the output stream for compiler output beyond that provided by + * diagnostics; {@code System.err} is used if this is {@code null}. + * @param fileManager the file manager to use or {@code null} to use a new + * instance from + * {@link #getStandardFileManaager(DiagnosticListener,Locale,Charset)} + * @param listener the listener to pass diagnostic output to, or + * {@code null} if the compiler's default method should + * be used instead. + * @param options the options to supply to the compiler or {@code null} if there are none. + * @param classes the names of classes to use for annotation processing or {@code null} + * if there are none. + * @param objects the file objects to compile, or {@code null} if there are none. + * @return a task representing the proposed compilation. + * @throws RuntimeException if an unrecoverable error occurred + * in a user-supplied component of + * the compilation process. The user + * exception will be provided as the + * cause of this exception. + * @throws IllegalArgumentException if the kind of any of the objects is something + * other than {@link JavaFileObject.Kind#SOURCE}. + */ + CompilationTask getTask(Writer out, JavaFileManager fileManager, + DiagnosticListener<? super JavaFileObject> listener, + Iterable<String> options, Iterable<String> classes, + Iterable<? extends JavaFileObject> objects); + +} diff --git a/javax/tools/JavaFileManager.java b/javax/tools/JavaFileManager.java new file mode 100644 index 000000000..990962c95 --- /dev/null +++ b/javax/tools/JavaFileManager.java @@ -0,0 +1,351 @@ +/* JavaFileManager.java -- File manager for source & class file tools. + 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.tools; + +import java.io.Closeable; +import java.io.Flushable; +import java.io.IOException; + +import java.util.Iterator; +import java.util.Set; + +/** + * <p>File manager for tools which operate on source and class files. + * In this context, the term {@code file} is used to refer to the abstract + * concept of a data source, rather than specifically a regular file on + * a filesystem.</p> + * <p>The file manager determines where to create new {@link FileObject}s. + * It may have a default directory where files are created. The user may + * provide hints as to how to perform file creation, but the file manager + * may choose to ignore these.</p> + * <p>For methods in this interface which use class names, these must + * be given in the internal virtual machine form of fully qualified + * class and interface names. The use of '/' and '.' are interchangeable, + * making {@code java.lang.Object}, {@code java/lang.Object} and + * {@code java/lang/Object} all equivalent.</p> + * <p>All names should be treated as being case-sensitive. If the underlying + * system is not case-aware, steps should be taken to handle this in the + * implementation, such as the use of {@link java.io.File#getCanonicalFile()} + * to preserve case.</p> + * <p>For methods in this interface which use relative names, these are + * path separated by {@code '/'} and do not include 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. The construction + * {@code URI.create(name).normalize().getPath().equals(name)} should hold.</p> + * <p>All methods may throw a {@link SecurityException}. All methods may + * throw a {@link NullPointerException} if an argument is null, unless + * otherwise specified. It is not required that the implementation support + * concurrent access to the file manager, but the file objects created by + * it should be thread-safe.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface JavaFileManager + extends Closeable, Flushable, OptionChecker +{ + + /** + * Interface for obtaining the location of {@link FileObject}s. + * Used by the file manager to know where to create or locate them. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ + public static interface Location + { + /** + * Returns the name of this location. + * + * @return the name. + */ + String getName(); + + /** + * Returns true if this location is used for output. + * + * @return true if the location is used for output. + */ + boolean isOutputLocation(); + } + + /** + * Closes the file manager and releases any resources in + * use. Calling {@code close()} on an already closed + * file manager has no effect. The effect of calling + * other methods on a closed file manager is undefined, + * unless specified in the documentation of that method. + * + * @throws IOException if an I/O error occurs. + * @see #flush() + */ + void close() throws IOException; + + /** + * Flushes data to any resources controlled by this file + * manager. Flushing a closed file manager has no effect. + * + * @throws IOException if an I/O error occurs. + * @see #close() + */ + void flush() throws IOException; + + /** + * Returns the class loader that is responsible for loading + * class files from the specified location. For example, + * {@code getClassLoader(StandardLocation.ANNOTATION_PROCESSOR_PATH)} + * will return the class loader which is used to load + * annotation processors. + * + * @param location the location to retrieve the class loader for. + * @return the class loader for class files in that location, or + * {@code null} if the location is unknown or class loading + * from that location is disabled. + * @throws SecurityException if the class loader is not retrievable + * under the current security manager. + * @throws IllegalStateException if {@link #close()} has been called + * and the file manager can't be reopened. + */ + ClassLoader getClassLoader(Location location); + + /** + * <p>Returns a file object for reading a file. If this + * is a source or class file, the returned instance + * must be a {@link JavaFileObject}. The file name is + * constructed as a concatenation of the location, the + * package name and the relative file name.</p> + * <p>For example, for the call + * {@ocode getFileForInput(StandardLocation.SOURCE_PATH, + * "gnu.classpath.util", "CoolCode.java")}, assuming + * that the source path is set to + * {@code "/home/bob/sources"}, the returned file object + * would represent the file + * {@code "/home/bob/sources/gnu/classpath/util/CoolCode.java"}.</p> + * + * @param location the base location for the file. + * @param pkg the package the file will be read from. + * @param relName the path to the file, relative to {@code location+pkg}. + * @return a file object or may return {@code null} if the file does not exist. + * @throws IllegalArgumentException if the location is unknown and unknown locations + * are not supported, or if the relative name is invalid. + * @throws IOException if an I/O error occurs, or the file manager + * has been closed and can't be reopened. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + FileObject getFileForInput(Location location, String pkg, String relName) + throws IOException; + + /** + * <p>Returns a file object for writing a file. If this + * is a source or class file, the returned instance + * must be a {@link JavaFileObject}. The file name is + * constructed as a concatenation of the location, the + * package name and the relative file name.</p> + * <p>For example, for the call + * {@ocode getFileForOutput(StandardLocation.SOURCE_OUTPUT, + * "gnu.classpath.util", "GenSyms.java")}, assuming + * that the source output is set to + * {@code "/home/bob/generated"}, the returned file object + * would represent the file + * {@code "/home/bob/generated/gnu/classpath/util/GenSyms.java"}.</p> + * <p>The file manager may optionally use the supplied + * sibling as a hint as to where to place the output file. + * The exact semantics of this hint are left to the implementation. + * As an example, the compiler places class files in the same location + * as the corresponding source file, if no destination is specified. + * To facilitate this, the source file location may be passed as + * a hint to the file manager.</p> + * + * @param location the base location for the file. + * @param pkg the package in which the file will be stored. + * @param relName the path to the file, relative to {@code location+pkg}. + * @param sibling an optional hint as to where to place the output file. + * May be {@code null}. + * @return a file object. + * @throws IllegalArgumentException if the location is unknown and unknown locations + * are not supported, if the relative name is invalid or + * if the sibling is not known to this file manager. + * @throws IOException if an I/O error occurs, or the file manager + * has been closed and can't be reopened. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + FileObject getFileForOutput(Location location, String pkg, String relName, + FileObject sibling) + throws IOException; + + /** + * <p>Returns a {@link JavaFileObject} for reading + * a source file or class file. The file name is + * constructed as a concatenation of the location + * and the information provided by the type name + * and the kind of the file.</p> + * <p>For example, for the call + * {@ocode getJavaFileForInput(StandardLocation.SOURCE_PATH, + * "gnu.classpath.util.CoolCode", JavaFileObject.Kind.SOURCE)}, + * assuming that the source path is set to + * {@code "/home/bob/sources"}, the returned file object + * would represent the file + * {@code "/home/bob/sources/gnu/classpath/util/CoolCode.java"}.</p> + * + * @param location the base location for the file. + * @param className the name of the class. + * @param kind the kind of file, either {@link JavaFileObject.Kind.SOURCE} or + * {@link JavaFileObject.Kind.CLASS}. + * @return a file object or may return {@code null} if the file does not exist. + * @throws IllegalArgumentException if the location is unknown and unknown locations + * are not supported, or if the kind is invalid. + * @throws IOException if an I/O error occurs, or the file manager + * has been closed and can't be reopened. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + JavaFileObject getJavaFileForInput(Location location, String className, JavaFileObject.Kind kind) + throws IOException; + + /** + * <p>Returns a {@link JavaFileObject} for writing a + * source or class file. The file name is + * constructed as a concatenation of the location and + * the information provided by the type name and the + * kind of the file.</p> + * <p>For example, for the call + * {@ocode getJavaFileForOutput(StandardLocation.CLASS_OUTPUT, + * "gnu.classpath.util.CoolCode", JavaFileObject.Kind.CLASS)}, assuming + * that the class output is set to + * {@code "/home/bob/build"}, the returned file object + * would represent the file + * {@code "/home/bob/build/gnu/classpath/util/GenSyms.class"}.</p> + * <p>The file manager may optionally use the supplied + * sibling as a hint as to where to place the output file. + * The exact semantics of this hint are left to the implementation. + * As an example, the compiler places class files in the same location + * as the corresponding source file, if no destination is specified. + * To facilitate this, the source file location may be passed as + * a hint to the file manager.</p> + * + * @param location the base location for the file. + * @param className the name of the class. + * @param kind the kind of file, either {@link JavaFileObject.Kind.SOURCE} or + * {@link JavaFileObject.Kind.CLASS}. + * @param sibling an optional hint as to where to place the output file. + * May be {@code null}. + * @return a file object. + * @throws IllegalArgumentException if the location is unknown and unknown locations + * are not supported, if the kind is invalid or + * if the sibling is not known to this file manager. + * @throws IOException if an I/O error occurs, or the file manager + * has been closed and can't be reopened. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + JavaFileObject getJavaFileForOutput(Location location, String className, + JavaFileObject.Kind kind, FileObject sibling) + throws IOException; + + /** + * Processes one option. If the specified option + * is supported by this file manager, it will read + * any necessary arguments to the option from the + * iterator and then return {@code true}. Otherwise, it + * will return {@code false}. + * + * @param option the option to process. + * @param remaining the remaining arguments/options. + * @return true if the option was handled. + * @throws IllegalArgumentException if the option is used incorrectly. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + boolean handleOption(String option, Iterator<String> remaining); + + /** + * Returns {@code true} if the specified location + * is known to this file manager. + * + * @param location the location to check. + * @return true if the location is known. + */ + boolean hasLocation(Location location); + + /** + * Infers a binary name for the given file object, + * based on its location. The returned name may + * not be a valid binary name, according to the + * Java language specification. + * + * @param location the location to use as a basis. + * @param file the file object. + * @return a binary name or {@code null} if the file + * object is not found in the given location. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + String inferBinaryName(Location location, JavaFileObject file); + + /** + * Returns true if the two given file objects represent + * the same file. + * + * @param x the first object. + * @param y the second object. + * @return true if {@code x} and {@code y} represent the + * same file. + * @throws IllegalArgumentException if either {@code x} or + * {@code y} were created by a foreign file manager and + * this file manager does not support such comparisons. + */ + boolean isSameFile(FileObject x, FileObject y); + + /** + * Lists all file objects matching the given criteria in the + * specified location. If {@code recurse} is true, the list + * will include those found in subpackages. Note that a file + * manager may not return a {@code null} list or throw an + * exception if the location is unknown. + * + * @param location the location to search. + * @param pkg the name of the package to search. + * @param kinds the kinds of object to return. + * @param recurse {@code true} if subpackages should be searched. + * @return an {@link Iterable} over the matching file object. + * @throws IOException if an I/O error occurs, or the file manager + * has been closed and can't be reopened. + * @throws IllegalStateException if the file manager has been closed and can't be reopened. + */ + Iterable<JavaFileObject> list(Location location, String pkg, + Set<JavaFileObject.Kind> kinds, boolean recurse) + throws IOException; + +} diff --git a/javax/tools/JavaFileObject.java b/javax/tools/JavaFileObject.java new file mode 100644 index 000000000..e8293316a --- /dev/null +++ b/javax/tools/JavaFileObject.java @@ -0,0 +1,125 @@ +/* JavaFileObject.java -- Abstraction for working with class & source files. + 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.tools; + +import javax.lang.model.element.Modifier; +import javax.lang.model.element.NestingKind; + +/** + * Abstraction for tools working with source and class files. + * All methods may throw a {@link SecurityException}. All + * methods may throw a {@link NullPointerException} if supplied + * with a {@code null} argument, unless otherwise specified. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface JavaFileObject + extends FileObject +{ + + /** + * Kinds of Java files. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ + public enum Kind + { + /** Java class files, which end in {@code ".class"} */ CLASS (".class"), + /** Web pages, which end in {@code "*.html"} */ HTML (".html"), + /** Any other kind of file. */ OTHER (""), + /** Java source files, which end in {@code ".java"} */ SOURCE (".java"); + + /** + * The file extension usually used for files of this + * type. If there is no conventional extension for + * this type, this field is set to the empty string, + * {@code ""}. + */ + public final String extension; + + Kind(String extension) + { + this.extension = extension; + } + + } + + /** + * Returns the kind of this file object. + * + * @return the kind. + */ + Kind getKind(); + + /** + * Checks if this file object represents the specified + * kind of file for the supplied type. The class name is + * a simple name i.e. not qualified. + * + * @param simpleName the simple name of the class. + * @param kind the kind of file. + * @return true if this object matches the type specified. + */ + boolean isNameCompatible(String simpleName, Kind kind); + + /** + * Provides a hint about the access level of this class, based + * on its modifiers. If the access level is unknown, or this + * file object does not represent a class file, {@code null} + * is returned. + * + * @return the access level. + */ + Modifier getAccessLevel(); + + /** + * Provides a hint about the nesting level of this class. + * It may return {@link NestingKind#MEMBER} instead of + * {@link NestingKind#LOCAL} or {@link NestingKind#ANONYMOUS} + * if it can not determine the exact type of nesting. If + * the nesting level is completely unknown, or this file + * object does not represent a class file, {@code null} + * is returned. + * + * @return the nesting level. + */ + NestingKind getNestingKind(); + +} diff --git a/javax/tools/OptionChecker.java b/javax/tools/OptionChecker.java new file mode 100644 index 000000000..13475d01f --- /dev/null +++ b/javax/tools/OptionChecker.java @@ -0,0 +1,59 @@ +/* OptionChecker.java -- Interface for recognising options. + 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.tools; + +/** + * Interface for recognising options. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface OptionChecker +{ + + /** + * Determines if the specified option is supported or not, + * and, if so, how many arguments it takes. + * + * @param option the name of the option. + * @return the number of arguments the option takes, or + * -1 if the option is not supported. + */ + int isSupportedOption(String option); + +} diff --git a/javax/tools/SimpleJavaFileObject.java b/javax/tools/SimpleJavaFileObject.java new file mode 100644 index 000000000..452858f12 --- /dev/null +++ b/javax/tools/SimpleJavaFileObject.java @@ -0,0 +1,281 @@ +/* SimpleJavaFileObject.java -- Simple implementation of JavaFileObject. + 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.tools; + +import java.io.InputStream; +import java.io.IOException; +import java.io.OutputStream; +import java.io.OutputStreamWriter; +import java.io.Reader; +import java.io.StringReader; +import java.io.Writer; + +import java.net.URI; + +import javax.lang.model.element.Modifier; +import javax.lang.model.element.NestingKind; + +/** + * Provides a simple implementation of many of the + * {@link JavaFileObject} methods, thus giving a useful basis + * for a subclass to complete the work. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public class SimpleJavaFileObject + implements JavaFileObject +{ + + /** + * The kind of this file object. + */ + protected Kind kind; + + /** + * The URI of this file object. + */ + protected URI uri; + + /** + * Constructs a new {@link SimpleJavaFileObject} + * of the specified kind using the supplied URI. + * + * @param uri the URI of this file object. + * @param kind the kind of this file object. + */ + protected SimpleJavaFileObject(URI uri, Kind kind) + { + this.uri = uri; + this.kind = kind; + } + + /** + * This implementation does nothing and always + * returns {@code false}. + * + * @return false. + */ + @Override + public boolean delete() + { + return false; + } + + /** + * This implementation throws {@link UnsupportedOperationException} + * and should be overridden in the subclass. + * + * @param ignoreEncodingErrors whether or not to ignore + * any encoding errors that + * occur. + * @return a character sequence if available. Otherwise {@code null}. + * @throws IOException if an I/O error occurs. + */ + @Override + public CharSequence getCharContent(boolean ignoreEncodingErrors) + throws IOException + { + throw new UnsupportedOperationException("getCharContent not implemented."); + } + + /** + * Returns a user-friendly name for this object. + * This implementation simply uses the path of the + * URI. + * + * @return a user-friendly name. + */ + @Override + public String getName() + { + return uri.getPath(); + } + + /** + * Returns the kind of this file object. + * + * @return {@code this.kind} + */ + @Override + public Kind getKind() + { + return kind; + } + + /** + * This implementation does nothing and always + * returns {@code 0L}. + * + * @return 0L. + */ + @Override + public long getLastModified() + { + return 0L; + } + + /** + * <p>Returns true if the given kind is the same as the + * kind of this file object, and the path of this + * object's URI is equal to the supplied name followed + * by the extension specified by its kind.</p> + * <p>This method uses {@link #getKind()} and + * {@link #toUri()} to retrieve the kind and URI + * respectively, so subclasses may override the values + * used.</p> + * + * @param simpleName the simple name to compare. + * @param kind the kind to compare. + * @return true if the above criteria are met. + */ + @Override + public boolean isNameCompatible(String simpleName, Kind kind) + { + return getKind().equals(kind) && + toUri().getPath().equals(simpleName + kind.extension); + } + + /** + * This implementation throws {@link UnsupportedOperationException} + * and should be overridden in the subclass. + * + * @return an input stream. + * @throws IOException if an I/O error occurs. + */ + @Override + public InputStream openInputStream() + throws IOException + { + throw new UnsupportedOperationException("openInputStream not implemented."); + } + + /** + * This implementation throws {@link UnsupportedOperationException} + * and should be overridden in the subclass. + * + * @return an output stream. + * @throws IOException if an I/O error occurs. + */ + @Override + public OutputStream openOutputStream() + throws IOException + { + throw new UnsupportedOperationException("openOutputStream not implemented."); + } + + /** + * Wraps the result of {@link #getCharContent(boolean)} + * in a {@link Reader}. + * + * @param ignoreEncodingErrors whether or not to ignore + * any encoding errors that + * occur. + * @return a Reader instance wrapping the result of + * {@code getCharContent(ignoreEncodingErrors)} + * @throws IllegalStateException if this file was opened for writing and + * does not support reading. + * @throws UnsupportedOperationException if this kind of file does not support + * character access. + * @throws IOException if an I/O error occurs. + */ + @Override + public Reader openReader(boolean ignoreEncodingErrors) + throws IOException + { + CharSequence content = getCharContent(ignoreEncodingErrors); + if (content == null) + throw new IllegalStateException("No character content available."); + return new StringReader(content.toString()); + } + + /** + * Wraps the result of {@link #openOutputStream()} + * in a {@link Writer}. + * + * @return a Writer instance wrapping the result + * of {@code openOutputStream()}. + * @throws IllegalStateException if this file was opened for reading and + * does not support writing. + * @throws UnsupportedOperationException if this kind of file does not support + * character access. + * @throws IOException if an I/O error occurs. + */ + @Override + public Writer openWriter() + throws IOException + { + return new OutputStreamWriter(openOutputStream()); + } + + /** + * Returns a {@link URI} identifying this object. + * + * @return a URI. + */ + @Override + public URI toUri() + { + return uri; + } + + /** + * This implementation does nothing and always + * returns {@code null}. + * + * @return null. + */ + @Override + public Modifier getAccessLevel() + { + return null; + } + + /** + * This implementation does nothing and always + * returns {@code null}. + * + * @return null. + */ + @Override + public NestingKind getNestingKind() + { + return null; + } + +} diff --git a/javax/tools/StandardJavaFileManager.java b/javax/tools/StandardJavaFileManager.java new file mode 100644 index 000000000..f938469a5 --- /dev/null +++ b/javax/tools/StandardJavaFileManager.java @@ -0,0 +1,166 @@ +/* StandardJavaFileManager.java -- File manager for regular files. + 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.tools; + +import java.io.File; +import java.io.IOException; + +/** + * <p>File manager for working with regular files or entries + * within file system containers, such as zip files. An + * implementation of this interface is usually retrieved using the + * {@link javax.tools.JavaCompiler#getStandardFileManager(DiagnosticListener,Locale,Charset)} + * of {@link javax.tools.JavaCompiler}, an instance of which + * is, in turn, returned from + * {@link javax.tools.ToolProvider#getSystemJavaCompiler()}.</p> + * <p>Regular file objects returned from a file manager implementing this + * interface must meet the following criteria:</p> + * <ul> + * <li>{@link FileObject#delete()} is equivalent to + * {@link java.io.File#delete()}.</li> + * <li>{@link FileObject#getLastModified} is equivalent to + * {@link java.io.File#lastModified}.</li> + * <li>Methods for reading input ({@link FileObject#getCharContent(boolean)}, + * {@link FileObject#openInputStream()}, + * {@link FileObject#openReader(boolean)}) must succeed, + * ignoring character encoding issues, if + * {@code new FileInputStream(new File(fileObj.toUri()))}.</li> + * <li>Methods for writing output ({@link FileObject#openOutputStream()}, + * {@link FileObject.openWriter()}) must succeed, + * ignoring character encoding issues, if + * {@code new FileOutputStream(new File(fileObj.toUri()))}.</li> + * <li><p>The URI returned from {@link FileObject#toUri()} must + * be have a schema and a normalised path component, which can + * be resolved without regard to context (i.e. it must be absolute, + * not relative to a particular directory). For example, the + * URI {@code file:///home/bob/sources} would be valid, while + * {@code file:sources} (not absolute) or + * {@code file:///home/bob/lib/../sources} (not normalised) would + * not.</li> + * </ul> + * <p>The file names used by the file objects need not be canonical.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface StandardJavaFileManager + extends JavaFileManager +{ + + /** + * Returns file objects representing the given files. This is + * a convenience method equivalent to calling + * {@code getJavaFileObjectsFromFiles(Arrays.asList(files))}. + * + * @param files the files to retrieve objects for. + * @return a list of file objects matching the specified array. + * @throws IllegalArgumentException if the array contains a directory. + * @throws NullPointerException if one of the array elements is {@code null}. + */ + Iterable<? extends JavaFileObject> getJavaFileObjects(File... files); + + /** + * Returns file objects representing the given file names. This is + * a convenience method equivalent to calling + * {@code getJavaFileObjectsFromString(Arrays.asList(fileNames))}. + * + * @param fileNames the file names to retrieve objects for. + * @return a list of file objects matching the specified array. + * @throws IllegalArgumentException if the array contains a directory. + * @throws NullPointerException if one of the array elements is {@code null}. + */ + Iterable<? extends JavaFileObject> getJavaFileObjects(String... files); + + /** + * Returns file objects representing the given files. + * + * @param files the files to retrieve objects for. + * @return a list of file objects. + * @throws IllegalArgumentException if the array contains a directory. + */ + Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files); + + /** + * Returns file objects representing the given file names. + * + * @param fileNames the file names to retrieve objects for. + * @return a list of file objects. + * @throws IllegalArgumentException if the array contains a directory. + */ + Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> files); + + /** + * Returns the list of paths associated with the specified location or + * {@code null} if there is no such mapping. Output locations only + * return a single path, representing the output directory. + * + * @param location the location whose path should be retrieved. + * @return the associated list of paths. + * @see #setLocation(Location,Iterable) + */ + Iterable<? extends File> getLocation(Location location); + + /** + * Returns true if the two file objects represent the same + * file. + * + * @param objA the first file object to compare. + * @param objB the second file object to compare. + * @return true if the two objects represent the same file. + * @throws IllegalArgumentException if either object was created + * by a different implementation. + */ + boolean isSameFile(FileObject objA, FileObject objB); + + /** + * Associates the given list of paths with the specified location, + * discarding any previous mapping. If the list is {@code null}, + * the mapping is reset to the default. + * + * @param location the location which will refer to this list of paths. + * @param paths a list of paths to associate with the location, or + * {@code null} to trigger a reset to the default list. + * @throws IllegalArgumentException if the location is an output location + * and the list contains more than one path. + * @throws IOException if the location is an output location but + * the list contains a path that isn't a directory. + * @see #getLocation(Location) + */ + void setLocation(Location location, Iterable<? extends File> paths) + throws IOException; +} diff --git a/javax/tools/StandardLocation.java b/javax/tools/StandardLocation.java new file mode 100644 index 000000000..bb4b70299 --- /dev/null +++ b/javax/tools/StandardLocation.java @@ -0,0 +1,119 @@ +/* StandardLocation.java -- Enumeration of standard file locations. + 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.tools; + +import java.util.concurrent.ConcurrentMap; +import java.util.concurrent.ConcurrentHashMap; + +import static javax.tools.JavaFileManager.Location; + +/** + * Enumeration of standard locations for storing + * {@link FileObject}s. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public enum StandardLocation + implements Location +{ + /** Location where annotation processors are found. */ + ANNOTATION_PROCESSOR_PATH { @Override public boolean isOutputLocation() { return false; } }, + /** Location to write class files to. */ + CLASS_OUTPUT { @Override public boolean isOutputLocation() { return true; } }, + /** Location where class files are found. */ + CLASS_PATH { @Override public boolean isOutputLocation() { return false; } }, + /** Location where platform class files are found. */ + PLATFORM_CLASS_PATH { @Override public boolean isOutputLocation() { return false; } }, + /** Location to write source files to. */ + SOURCE_OUTPUT { @Override public boolean isOutputLocation() { return true; } }, + /** Location where source files are found. */ + SOURCE_PATH { @Override public boolean isOutputLocation() { return false; } }; + + private static final ConcurrentMap<String,Location> locCache = + new ConcurrentHashMap<String,Location>(); + + static + { + for (StandardLocation loc : values()) + locCache.put(loc.name(), loc); + } + + /** + * Returns the name of the location. This is simply + * the enum constant. + * + * @return the name of the location. + */ + @Override + public String getName() + { + return name(); + } + + /** + * Returns an instance of {@link JavaFileManager.Location} + * for the given name. If the name is one of the standard + * names, the enumeration constant is returned. Otherwise, + * a new instance is generated. For location names {@code x} + * and {@code y}, {@code locationFor(x) == locationFor(y)} + * if, and only if, {@code x.equals(y)}. The returned location + * will only be an output location if the name ends with + * the suffix {@code "_OUTPUT"}. + * + * @param name the name of the location. + * @return the location. + */ + public static Location locationFor(String name) + { + final String locName = name; + Location loc = locCache.get(name); + if (loc == null) + { + loc = new Location() { + public String getName() { return locName; } + public boolean isOutputLocation() { return locName.endsWith("_OUTPUT"); } + }; + Location mapLoc = locCache.putIfAbsent(name, loc); + if (mapLoc != null) // Someone got there first + loc = mapLoc; + } + return loc; + } + +} diff --git a/javax/tools/Tool.java b/javax/tools/Tool.java new file mode 100644 index 000000000..a1b707029 --- /dev/null +++ b/javax/tools/Tool.java @@ -0,0 +1,84 @@ +/* Tool.java -- Interface for programatically-invokable tools. + 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.tools; + +import java.io.InputStream; +import java.io.OutputStream; + +import java.util.Set; + +import javax.lang.model.SourceVersion; + +/** + * Interface for tools than be invoked from a program. Tools + * can be located using {@link java.util.ServiceLoader#load(Class)}. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface Tool +{ + + /** + * Returns the set of source language versions that are supported + * by this tool. + * + * @return the set of supported source code versions. + */ + Set<SourceVersion> getSourceVersions(); + + /** + * Invokes the tool using the specified input/output streams and + * arguments, returning the same exit code it would if called from + * the command line. Traditionally, zero indicates success and non-zero + * is used for errors. Diagnostics from the tool will be written + * to {@code out} or {@code err} in a way specific to the tool. + * + * @param in the standard input for the tool or {@code null} to use + * {@code System.in}. + * @param out the standard output for the tool or {@code null} to use + * {@code System.out} + * @param err the standard error stream for the tool or {@code null} + * to use {@code System.err}. + * @param args the arguments to pass to the tool. + * @return the return code from the tool. + * @throws NullPointerException if any argument is {@code null}. + */ + int run(InputStream in, OutputStream out, OutputStream err, + String... arguments); +} |