Mercurial > jdk8-mips64-public > langtools / file revision

 /*

  * Copyright (c) 2005, 2013, Oracle and/or its affiliates. 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.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.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.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 annotations that are <em>present</em> on this element.

      *

      * If there are no annotations <em>present</em> on this element, the return

      * value is an array of length 0.

      *

      * The difference between this method and {@link #getAnnotation(Class)}

      * is that this method detects if its argument is a <em>repeatable

      * annotation type</em> (JLS 9.6), and if so, attempts to find one or more

      * annotations of that type by "looking through" a container annotation.

      *

      * <p> The annotations 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 annotations for the specified annotation

      *         type if present on this element, else an empty array

      *

      * @see #getAnnotationMirrors()

      * @see #getAnnotation(java.lang.Class)

      * @see java.lang.reflect.AnnotatedElement#getAnnotationsByType

      * @see EnumConstantNotPresentException

      * @see AnnotationTypeMismatchException

      * @see IncompleteAnnotationException

      * @see MirroredTypeException

      * @see MirroredTypesException

      */

     <A extends Annotation> A[] getAnnotationsByType(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 {@linkplain

      * PackageElement#getSimpleName package}, an empty name is

      * returned.

      *

      * If it represents a {@linkplain ExecutableElement#getSimpleName

      * constructor}, the name "{@code <init>}" is returned.  If it

      * represents a {@linkplain ExecutableElement#getSimpleName static

      * initializer}, the name "{@code <clinit>}" is returned.

      *

      * If it represents an {@linkplain TypeElement#getSimpleName

      * anonymous class} or {@linkplain ExecutableElement#getSimpleName

      * instance initializer}, an empty name is returned.

      *

      * @return the simple name of this element

      * @see PackageElement#getSimpleName

      * @see ExecutableElement#getSimpleName

      * @see TypeElement#getSimpleName

      * @see VariableElement#getSimpleName

      */

     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 {@linkplain TypeElement#getEnclosingElement

      * top-level type}, its package is returned.

      *

      * <li> If this is a {@linkplain

      * PackageElement#getEnclosingElement package}, {@code null} is

      * returned.

      *

      * <li> If this is a {@linkplain

      * TypeParameterElement#getEnclosingElement type parameter},

      * {@linkplain TypeParameterElement#getGenericElement the

      * generic element} of the type parameter is returned.

      *

      * <li> If this is a {@linkplain

      * VariableElement#getEnclosingElement method or constructor

      * parameter}, {@linkplain ExecutableElement the executable

      * element} which declares the parameter 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 {@linkplain TypeElement#getEnclosedElements class or

      * interface} is considered to enclose the fields, methods,

      * constructors, and member types that it directly declares.

      *

      * A {@linkplain PackageElement#getEnclosedElements 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 PackageElement#getEnclosedElements

      * @see TypeElement#getEnclosedElements

      * @see Elements#getAllMembers

      * @jls 8.8.9 Default Constructor

      * @jls 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 &quot;the same&quot;

      * 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);

 }