From 449a0b97ab63a4bff26ae281322fc3afaab16569 Mon Sep 17 00:00:00 2001 From: Andrew John Hughes Date: Tue, 27 Nov 2012 04:08:20 +0000 Subject: Add annotation elements and start of type hierarchy. 2012-11-26 Andrew John Hughes * javax/lang/model/element/AnnotationMirror.java: Added. (getAnnotationType()): Added. (getElementValues()): Likewise. * javax/lang/model/element/AnnotationValue.java: Added. (accept(AnnotationValueVisitor,P)): Added. (getValue()): Likewise. (toString()): Likewise. * javax/lang/model/element/AnnotationValueVisitor.java: Added. (visit(AnnotationValue)): Added. (visit(AnnotationValue, P)): Likewise. (visitAnnotation(AnnotationMirror, P)): Likewise. (visitArray(List, P)): Likewise. (visitBoolean(boolean, P)): Likewise. (visitByte(byte, P)): Likewise. (visitChar(char, P)): Likewise. (visitDouble(double, P)): Likewise. (visitEnumConstant(VariableElement, P)): Likewise. (visitFloat(float, P)): Likewise. (visitInt(float, P)): Likewise. (visitLong(long, P)): Likewise. (visitShort(short, P)): Likewise. (visitString(String, P)): Likewise. (visitType(TypeMirror, P)): Likewise. (visitUnknown(AnnotationValue, P)): Likewise. * javax/lang/model/element/Element.java: (asType()): Added. (getAnnotationMirrors()): Likewise. * javax/lang/model/element/ElementVisitor.java: (visitExecutable(ExecutableElement, P)): Added. (visitTypeParameter(TypeParameterElement, P)): Likewise. (visitVariable(VariableElement, P)): Likewise. * javax/lang/model/element/ExecutableElement.java: Added. (getDefaultValue()): Added. (getParameters()): Likewise. (getReturnType()): Likewise. (getThrownTypes()): Likewise. (getTypeParameters()): Likewise. (isVarArgs()): Likewise. * javax/lang/model/element/TypeElement.java: (getInterfaces()): Added. (getSuperclass()): Likewise. (getTypeParameters()): Likewise. * javax/lang/model/element/TypeParameterElement.java: Added. (getBounds()): Added. (getGenericElement()): Likewise. * javax/lang/model/element/VariableElement.java: Added. (getConstantValue()): Added. * javax/lang/model/type/DeclaredType.java: Added. (asElement()): Added. (getEnclosingType()): Likewise. (getTypeArguments()): Likewise. * javax/lang/model/type/ReferenceType.java: Added. * javax/lang/model/type/TypeKind.java: Added. (ARRAY): Added. (BOOLEAN): Likewise. (BYTE): Likewise. (CHAR): Likewise. (DECLARED): Likewise. (DOUBLE): Likewise. (ERROR): Likewise. (EXECUTABLE): Likewise. (FLOAT): Likewise. (INT): Likewise. (LONG): Likewise. (NONE): Likewise. (NULL): Likewise. (OTHER): Likewise. (PACKAGE): Likewise. (SHORT): Likewise. (TYPEVAR): Likewise. (VOID): Likewise. (WILDCARD): Likewise. (isPrimitive()): Implemented. * javax/lang/model/type/TypeMirror.java: Added. (accept(TypeVisitor, P)): Added. (equals(Object)): Likewise. (getKind()): Likewise. (hashCode()): Likewise. (toString()): Likewise. * javax/lang/model/type/TypeVisitor.java: Added. (visit(TypeMirror)): Added. (visit(TypeMirror, P)): Likewise. (visitUnknown(TypeMirror, P)): Likewise. (visitDeclared(DeclaredType, P)): Likewise. * javax/lang/model/util/Elements.java: (getAllAnnotationMirrors(Element)): Added. (getElementValuesWithDefaults(AnnotationMirror)): Likewise. (overrides(ExecutableElement, ExecutableElement)): Likewise. * javax/lang/model/util/Types.java: (asElement(TypeMirror)): Added. (asMemberOf(DeclaredType, Element)): Likewise. (capture(TypeMirror)): Likewise. (contains(TypeMirror, TypeMirror)): Likewise. (directSupertypes(TypeMirror)): Likewise. (erasure(TypeMirror)): Likewise. (getDeclaredType(DeclaredType, TypeElement, TypeMirror...)): Likewise. (getDeclaredType(TypeElement, TypeMirror...)): Likewise. (isAssignable(TypeMirror, TypeMirror)): Likewise. (isSameType(TypeMirror, TypeMirror)): Likewise. (isSubtype(TypeMirror, TypeMirror)): Likewise. Signed-off-by: Andrew John Hughes --- ChangeLog | 116 +++++++++++ javax/lang/model/element/AnnotationMirror.java | 78 +++++++ javax/lang/model/element/AnnotationValue.java | 86 ++++++++ .../lang/model/element/AnnotationValueVisitor.java | 224 +++++++++++++++++++++ javax/lang/model/element/Element.java | 28 +++ javax/lang/model/element/ElementVisitor.java | 29 ++- javax/lang/model/element/ExecutableElement.java | 113 +++++++++++ javax/lang/model/element/TypeElement.java | 36 ++++ javax/lang/model/element/TypeParameterElement.java | 82 ++++++++ javax/lang/model/element/VariableElement.java | 63 ++++++ javax/lang/model/type/DeclaredType.java | 101 ++++++++++ javax/lang/model/type/ReferenceType.java | 51 +++++ javax/lang/model/type/TypeKind.java | 112 +++++++++++ javax/lang/model/type/TypeMirror.java | 112 +++++++++++ javax/lang/model/type/TypeVisitor.java | 107 ++++++++++ javax/lang/model/util/Elements.java | 57 ++++++ javax/lang/model/util/Types.java | 166 +++++++++++++++ 17 files changed, 1560 insertions(+), 1 deletion(-) create mode 100644 javax/lang/model/element/AnnotationMirror.java create mode 100644 javax/lang/model/element/AnnotationValue.java create mode 100644 javax/lang/model/element/AnnotationValueVisitor.java create mode 100644 javax/lang/model/element/ExecutableElement.java create mode 100644 javax/lang/model/element/TypeParameterElement.java create mode 100644 javax/lang/model/element/VariableElement.java create mode 100644 javax/lang/model/type/DeclaredType.java create mode 100644 javax/lang/model/type/ReferenceType.java create mode 100644 javax/lang/model/type/TypeKind.java create mode 100644 javax/lang/model/type/TypeMirror.java create mode 100644 javax/lang/model/type/TypeVisitor.java diff --git a/ChangeLog b/ChangeLog index b1181e1d3..2e899c17f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,119 @@ +2012-11-26 Andrew John Hughes + + * javax/lang/model/element/AnnotationMirror.java: + Added. + (getAnnotationType()): Added. + (getElementValues()): Likewise. + * javax/lang/model/element/AnnotationValue.java: + Added. + (accept(AnnotationValueVisitor,P)): Added. + (getValue()): Likewise. + (toString()): Likewise. + * javax/lang/model/element/AnnotationValueVisitor.java: + Added. + (visit(AnnotationValue)): Added. + (visit(AnnotationValue, P)): Likewise. + (visitAnnotation(AnnotationMirror, P)): Likewise. + (visitArray(List, P)): Likewise. + (visitBoolean(boolean, P)): Likewise. + (visitByte(byte, P)): Likewise. + (visitChar(char, P)): Likewise. + (visitDouble(double, P)): Likewise. + (visitEnumConstant(VariableElement, P)): Likewise. + (visitFloat(float, P)): Likewise. + (visitInt(float, P)): Likewise. + (visitLong(long, P)): Likewise. + (visitShort(short, P)): Likewise. + (visitString(String, P)): Likewise. + (visitType(TypeMirror, P)): Likewise. + (visitUnknown(AnnotationValue, P)): Likewise. + * javax/lang/model/element/Element.java: + (asType()): Added. + (getAnnotationMirrors()): Likewise. + * javax/lang/model/element/ElementVisitor.java: + (visitExecutable(ExecutableElement, P)): Added. + (visitTypeParameter(TypeParameterElement, P)): Likewise. + (visitVariable(VariableElement, P)): Likewise. + * javax/lang/model/element/ExecutableElement.java: + Added. + (getDefaultValue()): Added. + (getParameters()): Likewise. + (getReturnType()): Likewise. + (getThrownTypes()): Likewise. + (getTypeParameters()): Likewise. + (isVarArgs()): Likewise. + * javax/lang/model/element/TypeElement.java: + (getInterfaces()): Added. + (getSuperclass()): Likewise. + (getTypeParameters()): Likewise. + * javax/lang/model/element/TypeParameterElement.java: + Added. + (getBounds()): Added. + (getGenericElement()): Likewise. + * javax/lang/model/element/VariableElement.java: + Added. + (getConstantValue()): Added. + * javax/lang/model/type/DeclaredType.java: + Added. + (asElement()): Added. + (getEnclosingType()): Likewise. + (getTypeArguments()): Likewise. + * javax/lang/model/type/ReferenceType.java: + Added. + * javax/lang/model/type/TypeKind.java: + Added. + (ARRAY): Added. + (BOOLEAN): Likewise. + (BYTE): Likewise. + (CHAR): Likewise. + (DECLARED): Likewise. + (DOUBLE): Likewise. + (ERROR): Likewise. + (EXECUTABLE): Likewise. + (FLOAT): Likewise. + (INT): Likewise. + (LONG): Likewise. + (NONE): Likewise. + (NULL): Likewise. + (OTHER): Likewise. + (PACKAGE): Likewise. + (SHORT): Likewise. + (TYPEVAR): Likewise. + (VOID): Likewise. + (WILDCARD): Likewise. + (isPrimitive()): Implemented. + * javax/lang/model/type/TypeMirror.java: + Added. + (accept(TypeVisitor, P)): Added. + (equals(Object)): Likewise. + (getKind()): Likewise. + (hashCode()): Likewise. + (toString()): Likewise. + * javax/lang/model/type/TypeVisitor.java: + Added. + (visit(TypeMirror)): Added. + (visit(TypeMirror, P)): Likewise. + (visitUnknown(TypeMirror, P)): Likewise. + (visitDeclared(DeclaredType, P)): Likewise. + * javax/lang/model/util/Elements.java: + (getAllAnnotationMirrors(Element)): Added. + (getElementValuesWithDefaults(AnnotationMirror)): Likewise. + (overrides(ExecutableElement, ExecutableElement)): Likewise. + * javax/lang/model/util/Types.java: + (asElement(TypeMirror)): Added. + (asMemberOf(DeclaredType, Element)): Likewise. + (capture(TypeMirror)): Likewise. + (contains(TypeMirror, TypeMirror)): Likewise. + (directSupertypes(TypeMirror)): Likewise. + (erasure(TypeMirror)): Likewise. + (getDeclaredType(DeclaredType, TypeElement, + TypeMirror...)): Likewise. + (getDeclaredType(TypeElement, TypeMirror...)): + Likewise. + (isAssignable(TypeMirror, TypeMirror)): Likewise. + (isSameType(TypeMirror, TypeMirror)): Likewise. + (isSubtype(TypeMirror, TypeMirror)): Likewise. + 2012-11-25 Andrew John Hughes * javax/annotation/processing/Processor.java: 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 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; + +/** + *

Represents the value of an element in an annotation. This + * may be one of the following types:

+ *
    + *
  • a wrapper class for a primitive type (e.g. {@code Integer} + * for {@code int}.
    • + *
  • {@code String}
    • + *
  • {@code TypeMirror}
    • + *
  • {@code VariableElement} (an enum constant)
    • + *
  • {@code AnnotationMirror}
    • + *
  • {@code List} (an array, + * with elements in the order they were declared)
    • + * + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface AnnotationValue +{ + + /** + * Applies a visitor to this type. + * + * @param the return type of the visitor's methods. + * @param

    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 accept(AnnotationValueVisitor 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..141aed6df --- /dev/null +++ b/javax/lang/model/element/AnnotationValueVisitor.java @@ -0,0 +1,224 @@ +/* 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; + +/** + *

    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}.

    + *

    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.

    + *

    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.

    + *

    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.

    + * + * @param the return type of the visitor's methods. {@code Void} + * can be used where there is no return value. + * @param

    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 +{ + + /** + * 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 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. + */ + R visitUnknown(AnnotationValue value, P param); + +} diff --git a/javax/lang/model/element/Element.java b/javax/lang/model/element/Element.java index 8f4adfbbf..aa01a8e91 100644 --- a/javax/lang/model/element/Element.java +++ b/javax/lang/model/element/Element.java @@ -41,6 +41,8 @@ import java.lang.annotation.Annotation; import java.util.List; +import javax.lang.model.type.TypeMirror; + /** *

    * Represents a program element at the language level. For example, @@ -159,4 +161,30 @@ public interface Element */ 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} will + * return the type {@code Set}. 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 getAnnotationMirrors(); + } diff --git a/javax/lang/model/element/ElementVisitor.java b/javax/lang/model/element/ElementVisitor.java index fd184c968..656795daa 100644 --- a/javax/lang/model/element/ElementVisitor.java +++ b/javax/lang/model/element/ElementVisitor.java @@ -66,7 +66,7 @@ public interface ElementVisitor /** * A convenience method for use when there is no additional - * parameter to pass. This is equivalent to {@code #visit(e, null)}. + * 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. @@ -103,4 +103,31 @@ public interface ElementVisitor */ R visitUnknown(Element element, P param); + /** + * Visits an executable 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 visitExecutable(ExecutableElement element, P param); + + /** + * Visits a type parameter 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 visitTypeParameter(TypeParameterElement element, P param); + + /** + * Visits a variable 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 visitVariable(VariableElement 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 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 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 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/TypeElement.java b/javax/lang/model/element/TypeElement.java index 6cc0c6805..c6b76197e 100644 --- a/javax/lang/model/element/TypeElement.java +++ b/javax/lang/model/element/TypeElement.java @@ -37,6 +37,10 @@ exception statement from your version. */ package javax.lang.model.element; +import java.util.List; + +import javax.lang.model.type.TypeMirror; + /** *

    Represents a class or interface program element. * Note that enumerations are a kind of class and annotations @@ -63,4 +67,36 @@ package javax.lang.model.element; 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 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 getTypeParameters(); + } 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} would be a single element + * list containing the type mirror for {@code Integer}. Similarly, + * for {@code Set}, 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 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/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/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; + +/** + *

    Represents a type declared in the source code i.e. a class + * or an interface. This includes parameterised types, such + * as {@code Set} as well as raw types, such as {@code Set}.

    + *

    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} and {@code Set} types mentioned above + * would be represented by the same element.

    + *

    This interface is also used to represent intersection types + * which don't exist explicitly in the source code. For example, + * in {@code }, 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.

    + *

    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.

    + * + * @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} + * 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}, 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 getTypeArguments(); + +} 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; + +/** + *

    + * 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). + *

    + *

    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.

    + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.6 + */ +public interface TypeMirror +{ + + /** + * Applies a visitor to this type. + * + * @param the return type of the visitor's methods. + * @param

    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 accept(TypeVisitor 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/TypeVisitor.java b/javax/lang/model/type/TypeVisitor.java new file mode 100644 index 000000000..ea00f5227 --- /dev/null +++ b/javax/lang/model/type/TypeVisitor.java @@ -0,0 +1,107 @@ +/* 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; + +/** + *

    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.

    + *

    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.

    + *

    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.

    + * + * @param the return type of the visitor's methods. {@code Void} + * can be used where there is no return value. + * @param

    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 +{ + + /** + * 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. + */ + 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); + +} diff --git a/javax/lang/model/util/Elements.java b/javax/lang/model/util/Elements.java index 67f89ef65..a3f7e2a3b 100644 --- a/javax/lang/model/util/Elements.java +++ b/javax/lang/model/util/Elements.java @@ -40,8 +40,12 @@ 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.TypeElement; /** @@ -121,4 +125,57 @@ public interface Elements */ 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 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 + getElementValuesWithDefaults(AnnotationMirror annotation); + + /** + *

    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.

    + *

    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.

    + * + * @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); + } diff --git a/javax/lang/model/util/Types.java b/javax/lang/model/util/Types.java index 18eb58098..b05008c77 100644 --- a/javax/lang/model/util/Types.java +++ b/javax/lang/model/util/Types.java @@ -37,6 +37,14 @@ 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.DeclaredType; +import javax.lang.model.type.TypeMirror; + /** * Utility methods for operating on types. * @@ -45,4 +53,162 @@ package javax.lang.model.util; */ 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}. + * + * @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 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); + + /** + *

    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.Inner}. To obtain this type, + * this method should be supplied with the {@link DeclaredType} + * for {@code Outer} (probably obtained by a call + * to {@link #getDeclaredType(TypeElement, TypeMirror...)}), + * the element representing {@code Inner} and the + * {@link TypeMirror} for {@code String}

    . + *

    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}, + * and the type mirror for {@code String}, this method would + * return the declared type for {@code Set}. 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); + } -- cgit v1.2.1