/*
* Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code 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
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package javax.lang.model.element;
import java.lang.annotation.Annotation;
import java.lang.annotation.AnnotationTypeMismatchException;
import java.lang.annotation.IncompleteAnnotationException;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.Modifier;
import javax.lang.model.type.*;
import javax.lang.model.util.*;
/**
* Represents a program element such as a package, class, or method.
* Each element represents a static, language-level construct
* (and not, for example, a runtime construct of the virtual machine).
*
* <p> Elements should be compared using the {@link #equals(Object)}
* method. There is no guarantee that any particular element will
* always be represented by the same object.
*
* <p> To implement operations based on the class of an {@code
* Element} object, either use a {@linkplain ElementVisitor visitor} or
* use the result of the {@link #getKind} method. Using {@code
* instanceof} is <em>not</em> necessarily a reliable idiom for
* determining the effective class of an object in this modeling
* hierarchy since an implementation may choose to have a single object
* implement multiple {@code Element} subinterfaces.
*
* @author Joseph D. Darcy
* @author Scott Seligman
* @author Peter von der Ahé
* @see Elements
* @see TypeMirror
* @since 1.6
*/
public interface Element {
/**
* Returns the type defined by this element.
*
* <p> A generic element defines a family of types, not just one.
* If this is a generic element, a <i>prototypical</i> type is
* returned. This is the element's invocation on the
* type variables corresponding to its own formal type parameters.
* For example,
* for the generic class element {@code C<N extends Number>},
* the parameterized type {@code C<N>} is returned.
* The {@link Types} utility interface has more general methods
* for obtaining the full range of types defined by an element.
*
* @see Types
*
* @return the type defined by this element
*/
TypeMirror asType();
/**
* Returns the {@code kind} of this element.
*
* @return the kind of this element
*/
ElementKind getKind();
/**
* Returns the annotations that are directly present on this element.
*
* <p> To get inherited annotations as well, use
* {@link Elements#getAllAnnotationMirrors(Element) getAllAnnotationMirrors}.
*
* @see ElementFilter
*
* @return the annotations directly present on this element;
* an empty list if there are none
*/
List<? extends AnnotationMirror> getAnnotationMirrors();
/**
* Returns this element's annotation for the specified type if
* such an annotation is present, else {@code null}. The
* annotation may be either inherited or directly present on this
* element.
*
* <p> The annotation returned by this method could contain an element
* whose value is of type {@code Class}.
* This value cannot be returned directly: information necessary to
* locate and load a class (such as the class loader to use) is
* not available, and the class might not be loadable at all.
* Attempting to read a {@code Class} object by invoking the relevant
* method on the returned annotation
* will result in a {@link MirroredTypeException},
* from which the corresponding {@link TypeMirror} may be extracted.
* Similarly, attempting to read a {@code Class[]}-valued element
* will result in a {@link MirroredTypesException}.
*
* <blockquote>
* <i>Note:</i> This method is unlike others in this and related
* interfaces. It operates on runtime reflective information —
* representations of annotation types currently loaded into the
* VM — rather than on the representations defined by and used
* throughout these interfaces. Consequently, calling methods on
* the returned annotation object can throw many of the exceptions
* that can be thrown when calling methods on an annotation object
* returned by core reflection. This method is intended for
* callers that are written to operate on a known, fixed set of
* annotation types.
* </blockquote>
*
* @param <A> the annotation type
* @param annotationType the {@code Class} object corresponding to
* the annotation type
* @return this element's annotation for the specified annotation
* type if present on this element, else {@code null}
*
* @see #getAnnotationMirrors()
* @see java.lang.reflect.AnnotatedElement#getAnnotation
* @see EnumConstantNotPresentException
* @see AnnotationTypeMismatchException
* @see IncompleteAnnotationException
* @see MirroredTypeException
* @see MirroredTypesException
*/
<A extends Annotation> A getAnnotation(Class<A> annotationType);
/**
* Returns the modifiers of this element, excluding annotations.
* Implicit modifiers, such as the {@code public} and {@code static}
* modifiers of interface members, are included.
*
* @return the modifiers of this element, or an empty set if there are none
*/
Set<Modifier> getModifiers();
/**
* Returns the simple (unqualified) name of this element.
* The name of a generic type does not include any reference
* to its formal type parameters.
* For example, the simple name of the type element
* {@code java.util.Set<E>} is {@code "Set"}.
* If this element represents an unnamed package, an empty name is
* returned. If it represents a constructor, the name "{@code
* <init>}" is returned. If it represents a static initializer,
* the name "{@code <clinit>}" is returned. If it represents an
* anonymous class or instance initializer, an empty name is
* returned.
*
* @return the simple name of this element
*/
Name getSimpleName();
/**
* Returns the innermost element
* within which this element is, loosely speaking, enclosed.
* <ul>
* <li> If this element is one whose declaration is lexically enclosed
* immediately within the declaration of another element, that other
* element is returned.
* <li> If this is a top-level type, its package is returned.
* <li> If this is a package, {@code null} is returned.
* <li> If this is a type parameter, {@code null} is returned.
* </ul>
*
* @return the enclosing element, or {@code null} if there is none
* @see Elements#getPackageOf
*/
Element getEnclosingElement();
/**
* Returns the elements that are, loosely speaking, directly
* enclosed by this element.
*
* A class or interface is considered to enclose the fields,
* methods, constructors, and member types that it directly
* declares. This includes any (implicit) default constructor and
* the implicit {@code values} and {@code valueOf} methods of an
* enum type.
*
* A package encloses the top-level classes and interfaces within
* it, but is not considered to enclose subpackages.
*
* Other kinds of elements are not currently considered to enclose
* any elements; however, that may change as this API or the
* programming language evolves.
*
* <p>Note that elements of certain kinds can be isolated using
* methods in {@link ElementFilter}.
*
* @return the enclosed elements, or an empty list if none
* @see Elements#getAllMembers
* @jls3 8.8.9 Default Constructor
* @jls3 8.9 Enums
*/
List<? extends Element> getEnclosedElements();
/**
* Returns {@code true} if the argument represents the same
* element as {@code this}, or {@code false} otherwise.
*
* <p>Note that the identity of an element involves implicit state
* not directly accessible from the element's methods, including
* state about the presence of unrelated types. Element objects
* created by different implementations of these interfaces should
* <i>not</i> be expected to be equal even if "the same"
* element is being modeled; this is analogous to the inequality
* of {@code Class} objects for the same class file loaded through
* different class loaders.
*
* @param obj the object to be compared with this element
* @return {@code true} if the specified object represents the same
* element as this
*/
boolean equals(Object obj);
/**
* Obeys the general contract of {@link Object#hashCode Object.hashCode}.
*
* @see #equals
*/
int hashCode();
/**
* Applies a visitor to this element.
*
* @param <R> the return type of the visitor's methods
* @param <P> the type of the additional parameter to the visitor's methods
* @param v the visitor operating on this element
* @param p additional parameter to the visitor
* @return a visitor-specified result
*/
<R, P> R accept(ElementVisitor<R, P> v, P p);
}