Elements should be compared using the {@link #equals(Object)} duke@1: * method. There is no guarantee that any particular element will duke@1: * always be represented by the same object. duke@1: * duke@1: *
To implement operations based on the class of an {@code duke@1: * Element} object, either use a {@linkplain ElementVisitor visitor} or duke@1: * use the result of the {@link #getKind} method. Using {@code duke@1: * instanceof} is not necessarily a reliable idiom for duke@1: * determining the effective class of an object in this modeling duke@1: * hierarchy since an implementation may choose to have a single object duke@1: * implement multiple {@code Element} subinterfaces. duke@1: * duke@1: * @author Joseph D. Darcy duke@1: * @author Scott Seligman duke@1: * @author Peter von der Ahé duke@1: * @see Elements duke@1: * @see TypeMirror duke@1: * @since 1.6 duke@1: */ duke@1: public interface Element { duke@1: duke@1: /** duke@1: * Returns the type defined by this element. duke@1: * duke@1: *
A generic element defines a family of types, not just one.
duke@1: * If this is a generic element, a prototypical type is
duke@1: * returned. This is the element's invocation on the
duke@1: * type variables corresponding to its own formal type parameters.
duke@1: * For example,
duke@1: * for the generic class element {@code C To get inherited annotations as well, use
duke@1: * {@link Elements#getAllAnnotationMirrors(Element) getAllAnnotationMirrors}.
duke@1: *
duke@1: * @see ElementFilter
duke@1: *
duke@1: * @return the annotations directly present on this element;
duke@1: * an empty list if there are none
duke@1: */
duke@1: List getAnnotationMirrors();
duke@1:
duke@1: /**
duke@1: * Returns this element's annotation for the specified type if
duke@1: * such an annotation is present, else {@code null}. The
duke@1: * annotation may be either inherited or directly present on this
duke@1: * element.
duke@1: *
duke@1: * The annotation returned by this method could contain an element
duke@1: * whose value is of type {@code Class}.
duke@1: * This value cannot be returned directly: information necessary to
duke@1: * locate and load a class (such as the class loader to use) is
duke@1: * not available, and the class might not be loadable at all.
duke@1: * Attempting to read a {@code Class} object by invoking the relevant
duke@1: * method on the returned annotation
duke@1: * will result in a {@link MirroredTypeException},
duke@1: * from which the corresponding {@link TypeMirror} may be extracted.
duke@1: * Similarly, attempting to read a {@code Class[]}-valued element
duke@1: * will result in a {@link MirroredTypesException}.
duke@1: *
duke@1: * The annotations returned by this method could contain an element
jfranck@1491: * whose value is of type {@code Class}.
jfranck@1491: * This value cannot be returned directly: information necessary to
jfranck@1491: * locate and load a class (such as the class loader to use) is
jfranck@1491: * not available, and the class might not be loadable at all.
jfranck@1491: * Attempting to read a {@code Class} object by invoking the relevant
jfranck@1491: * method on the returned annotation
jfranck@1491: * will result in a {@link MirroredTypeException},
jfranck@1491: * from which the corresponding {@link TypeMirror} may be extracted.
jfranck@1491: * Similarly, attempting to read a {@code Class[]}-valued element
jfranck@1491: * will result in a {@link MirroredTypesException}.
jfranck@1491: *
jfranck@1491: * Note that elements of certain kinds can be isolated using
duke@1: * methods in {@link ElementFilter}.
duke@1: *
duke@1: * @return the enclosed elements, or an empty list if none
darcy@1181: * @see PackageElement#getEnclosedElements
darcy@1181: * @see TypeElement#getEnclosedElements
duke@1: * @see Elements#getAllMembers
jjh@972: * @jls 8.8.9 Default Constructor
jjh@972: * @jls 8.9 Enums
duke@1: */
duke@1: List getEnclosedElements();
duke@1:
duke@1: /**
duke@1: * Returns {@code true} if the argument represents the same
duke@1: * element as {@code this}, or {@code false} otherwise.
duke@1: *
duke@1: * Note that the identity of an element involves implicit state
duke@1: * not directly accessible from the element's methods, including
duke@1: * state about the presence of unrelated types. Element objects
duke@1: * created by different implementations of these interfaces should
duke@1: * not be expected to be equal even if "the same"
duke@1: * element is being modeled; this is analogous to the inequality
duke@1: * of {@code Class} objects for the same class file loaded through
duke@1: * different class loaders.
duke@1: *
duke@1: * @param obj the object to be compared with this element
duke@1: * @return {@code true} if the specified object represents the same
duke@1: * element as this
duke@1: */
duke@1: boolean equals(Object obj);
duke@1:
duke@1: /**
duke@1: * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
duke@1: *
duke@1: * @see #equals
duke@1: */
duke@1: int hashCode();
duke@1:
duke@1: /**
duke@1: * Applies a visitor to this element.
duke@1: *
duke@1: * @param the type of the additional parameter to the visitor's methods
duke@1: * @param v the visitor operating on this element
duke@1: * @param p additional parameter to the visitor
duke@1: * @return a visitor-specified result
duke@1: */
duke@1:
duke@1: * Note: This method is unlike others in this and related
duke@1: * interfaces. It operates on runtime reflective information —
duke@1: * representations of annotation types currently loaded into the
duke@1: * VM — rather than on the representations defined by and used
duke@1: * throughout these interfaces. Consequently, calling methods on
duke@1: * the returned annotation object can throw many of the exceptions
duke@1: * that can be thrown when calling methods on an annotation object
duke@1: * returned by core reflection. This method is intended for
duke@1: * callers that are written to operate on a known, fixed set of
duke@1: * annotation types.
duke@1: *
duke@1: *
duke@1: * @param the annotation type
duke@1: * @param annotationType the {@code Class} object corresponding to
duke@1: * the annotation type
duke@1: * @return this element's annotation for the specified annotation
duke@1: * type if present on this element, else {@code null}
duke@1: *
duke@1: * @see #getAnnotationMirrors()
duke@1: * @see java.lang.reflect.AnnotatedElement#getAnnotation
duke@1: * @see EnumConstantNotPresentException
duke@1: * @see AnnotationTypeMismatchException
duke@1: * @see IncompleteAnnotationException
duke@1: * @see MirroredTypeException
duke@1: * @see MirroredTypesException
duke@1: */
duke@1: A getAnnotation(Class annotationType);
duke@1:
duke@1: /**
jfranck@1491: * Returns an array of all of this element's annotation for the
jfranck@1491: * specified type if such annotations are present, else an empty
jfranck@1491: * array. The annotation may be either inherited or directly
jfranck@1491: * present on this element. This method will look through a container
jfranck@1491: * annotation (if present) if the supplied annotation type is
jfranck@1491: * repeatable.
jfranck@1491: *
jfranck@1491: *
jfranck@1491: * Note: This method is unlike others in this and related
jfranck@1491: * interfaces. It operates on runtime reflective information —
jfranck@1491: * representations of annotation types currently loaded into the
jfranck@1491: * VM — rather than on the representations defined by and used
jfranck@1491: * throughout these interfaces. Consequently, calling methods on
jfranck@1491: * the returned annotation object can throw many of the exceptions
jfranck@1491: * that can be thrown when calling methods on an annotation object
jfranck@1491: * returned by core reflection. This method is intended for
jfranck@1491: * callers that are written to operate on a known, fixed set of
jfranck@1491: * annotation types.
jfranck@1491: *
jfranck@1491: *
jfranck@1491: * @param the annotation type
jfranck@1491: * @param annotationType the {@code Class} object corresponding to
jfranck@1491: * the annotation type
jfranck@1491: * @return this element's annotations for the specified annotation
jfranck@1491: * type if present on this element, else an empty array
jfranck@1491: *
jfranck@1491: * @see #getAnnotationMirrors()
jfranck@1491: * @see #getAnnotation()
jfranck@1491: * @see java.lang.reflect.AnnotatedElement#getAnnotations
jfranck@1491: * @see EnumConstantNotPresentException
jfranck@1491: * @see AnnotationTypeMismatchException
jfranck@1491: * @see IncompleteAnnotationException
jfranck@1491: * @see MirroredTypeException
jfranck@1491: * @see MirroredTypesException
jfranck@1491: */
jfranck@1491: A[] getAnnotations(Class annotationType);
jfranck@1491:
jfranck@1491: /**
duke@1: * Returns the modifiers of this element, excluding annotations.
duke@1: * Implicit modifiers, such as the {@code public} and {@code static}
duke@1: * modifiers of interface members, are included.
duke@1: *
duke@1: * @return the modifiers of this element, or an empty set if there are none
duke@1: */
duke@1: Set
duke@1: *
duke@1: *
duke@1: * @return the enclosing element, or {@code null} if there is none
duke@1: * @see Elements#getPackageOf
duke@1: */
duke@1: Element getEnclosingElement();
duke@1:
duke@1: /**
duke@1: * Returns the elements that are, loosely speaking, directly
duke@1: * enclosed by this element.
duke@1: *
darcy@1181: * A {@linkplain TypeElement#getEnclosedElements class or
darcy@1181: * interface} is considered to enclose the fields, methods,
darcy@1181: * constructors, and member types that it directly declares.
duke@1: *
darcy@1181: * A {@linkplain PackageElement#getEnclosedElements package}
darcy@1181: * encloses the top-level classes and interfaces within it, but is
darcy@1181: * not considered to enclose subpackages.
duke@1: *
duke@1: * Other kinds of elements are not currently considered to enclose
duke@1: * any elements; however, that may change as this API or the
duke@1: * programming language evolves.
duke@1: *
duke@1: *