russell@unturf.com
0a580b313d
Authors: russell@unturf.com · brackishbert@gmail.com · foxhop.net · TimeHexOn.com Patches, unit tests, benchmarks, whitepaper, and outreach briefs. Public domain — no copyright claimed. Use freely.
307 lines
11 KiB
Java
307 lines
11 KiB
Java
/*
|
|
* Copyright (c) 2005, 2024, 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.util.List;
|
|
import java.util.Set;
|
|
|
|
import javax.lang.model.AnnotatedConstruct;
|
|
import javax.lang.model.type.*;
|
|
import javax.lang.model.util.*;
|
|
|
|
/**
|
|
* Represents a program element such as a module, package, class, or method.
|
|
* Each element represents a compile-time 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.
|
|
*
|
|
* @see Elements
|
|
* @see TypeMirror
|
|
* @since 1.6
|
|
*/
|
|
public interface Element extends AnnotatedConstruct {
|
|
/**
|
|
* {@return the type defined by this element}
|
|
*
|
|
* @see Types
|
|
* @see ExecutableElement#asType
|
|
* @see ModuleElement#asType
|
|
* @see PackageElement#asType
|
|
* @see TypeElement#asType
|
|
* @see TypeParameterElement#asType
|
|
* @see VariableElement#asType
|
|
* @see RecordComponentElement#asType
|
|
*/
|
|
TypeMirror asType();
|
|
|
|
/**
|
|
* {@return the {@code kind} of this element}
|
|
*
|
|
* <ul>
|
|
*
|
|
* <li> The kind of a {@linkplain PackageElement package} is
|
|
* {@link ElementKind#PACKAGE PACKAGE}.
|
|
*
|
|
* <li> The kind of a {@linkplain ModuleElement module} is {@link
|
|
* ElementKind#MODULE MODULE}.
|
|
*
|
|
* <li> The kind of a {@linkplain TypeElement type element} is one
|
|
* of {@link ElementKind#ANNOTATION_TYPE ANNOTATION_TYPE}, {@link
|
|
* ElementKind#CLASS CLASS}, {@link ElementKind#ENUM ENUM}, {@link
|
|
* ElementKind#INTERFACE INTERFACE}, or {@link ElementKind#RECORD
|
|
* RECORD}.
|
|
*
|
|
* <li> The kind of a {@linkplain VariableElement variable} is one
|
|
* of {@link ElementKind#ENUM_CONSTANT ENUM_CONSTANT}, {@link
|
|
* ElementKind#EXCEPTION_PARAMETER EXCEPTION_PARAMETER}, {@link
|
|
* ElementKind#FIELD FIELD}, {@link ElementKind#LOCAL_VARIABLE
|
|
* LOCAL_VARIABLE}, {@link ElementKind#PARAMETER PARAMETER},
|
|
* {@link ElementKind#RESOURCE_VARIABLE RESOURCE_VARIABLE}, or
|
|
* {@link ElementKind#BINDING_VARIABLE BINDING_VARIABLE}.
|
|
*
|
|
* <li> The kind of an {@linkplain ExecutableElement executable}
|
|
* is one of {@link ElementKind#CONSTRUCTOR CONSTRUCTOR}, {@link
|
|
* ElementKind#INSTANCE_INIT INSTANCE_INIT}, {@link
|
|
* ElementKind#METHOD METHOD}, or {@link ElementKind#STATIC_INIT
|
|
* STATIC_INIT}.
|
|
*
|
|
* <li> The kind of a {@linkplain TypeParameterElement type parameter} is
|
|
* {@link ElementKind#TYPE_PARAMETER TYPE_PARAMETER}.
|
|
*
|
|
* <li> The kind of a {@linkplain RecordComponentElement record
|
|
* component} is {@link ElementKind#RECORD_COMPONENT
|
|
* RECORD_COMPONENT}.
|
|
*
|
|
* </ul>
|
|
*/
|
|
ElementKind getKind();
|
|
|
|
/**
|
|
* Returns the modifiers of this element, excluding annotations.
|
|
* Implicit modifiers, such as the {@code public} and {@code
|
|
* static} modifiers of interface members (JLS section {@jls
|
|
* 9.3}), are included.
|
|
*
|
|
* @return the modifiers of this element, or an empty set if there are none
|
|
*/
|
|
Set<Modifier> getModifiers();
|
|
|
|
/**
|
|
* {@return the simple (unqualified) name of this element} The
|
|
* name of a generic class or interface does not include any
|
|
* reference to its formal type parameters.
|
|
*
|
|
* For example, the simple name of the type element representing
|
|
* {@code java.util.Set<E>} is {@code "Set"}.
|
|
*
|
|
* If this element represents an unnamed {@linkplain
|
|
* PackageElement#getSimpleName package}, an unnamed {@linkplain
|
|
* ModuleElement#getSimpleName module} or an unnamed {@linkplain
|
|
* VariableElement#getSimpleName variable}, an {@linkplain Name##empty_name 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 {@linkplain Name##empty_name empty
|
|
* name} is returned.
|
|
*
|
|
* @see PackageElement#getSimpleName
|
|
* @see ExecutableElement#getSimpleName
|
|
* @see TypeElement#getSimpleName
|
|
* @see VariableElement#getSimpleName
|
|
* @see ModuleElement#getSimpleName
|
|
* @see RecordComponentElement#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 class or interface}, its package is returned.
|
|
*
|
|
* <li> If this is a {@linkplain
|
|
* PackageElement#getEnclosingElement package}, its module is
|
|
* returned if such a module exists. Otherwise, {@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.
|
|
*
|
|
* <li> If this is a {@linkplain
|
|
* RecordComponentElement#getEnclosingElement record component},
|
|
* {@linkplain TypeElement the record class} which declares the
|
|
* record component is returned.
|
|
*
|
|
* <li> If this is a {@linkplain ModuleElement#getEnclosingElement
|
|
* module}, {@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 {@linkplain TypeElement#getEnclosedElements class or
|
|
* interface} is considered to enclose the fields, methods,
|
|
* constructors, record components, and member classes and interfaces 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.
|
|
*
|
|
* A {@linkplain ModuleElement#getEnclosedElements module}
|
|
* encloses packages within it.
|
|
*
|
|
* Enclosed elements may include implicitly declared {@linkplain
|
|
* Elements.Origin#MANDATED mandated} elements.
|
|
*
|
|
* Other kinds of elements are not currently considered to enclose
|
|
* any elements; however, that may change as this API or the
|
|
* programming language evolves.
|
|
*
|
|
* @apiNote Elements of certain kinds can be isolated using
|
|
* methods in {@link ElementFilter}.
|
|
*
|
|
* @return the enclosed elements, or an empty list if none
|
|
* @see TypeElement#getEnclosedElements
|
|
* @see PackageElement#getEnclosedElements
|
|
* @see ModuleElement#getEnclosedElements
|
|
* @see Elements#getAllMembers
|
|
* @jls 8.8.9 Default Constructor
|
|
* @jls 8.9 Enum Classes
|
|
* @jls 8.10 Record Classes
|
|
*/
|
|
List<? extends Element> getEnclosedElements();
|
|
|
|
/**
|
|
* {@return {@code true} if the argument represents the same
|
|
* element as {@code this}, or {@code false} otherwise}
|
|
*
|
|
* @apiNote 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
|
|
*/
|
|
@Override
|
|
boolean equals(Object obj);
|
|
|
|
/**
|
|
* Obeys the general contract of {@link Object#hashCode Object.hashCode}.
|
|
*
|
|
* @see #equals
|
|
*/
|
|
@Override
|
|
int hashCode();
|
|
|
|
/**
|
|
* {@inheritDoc AnnotatedConstruct}
|
|
*
|
|
* <p>To get inherited annotations as well, use {@link
|
|
* Elements#getAllAnnotationMirrors(Element)
|
|
* getAllAnnotationMirrors}.
|
|
*
|
|
* <p>Note that any annotations returned by this method are
|
|
* declaration annotations.
|
|
*
|
|
* @since 1.6
|
|
*/
|
|
@Override
|
|
List<? extends AnnotationMirror> getAnnotationMirrors();
|
|
|
|
/**
|
|
* {@inheritDoc AnnotatedConstruct}
|
|
*
|
|
* <p>Note that any annotation returned by this method is a
|
|
* declaration annotation.
|
|
*
|
|
* @since 1.6
|
|
*/
|
|
@Override
|
|
<A extends Annotation> A getAnnotation(Class<A> annotationType);
|
|
|
|
/**
|
|
* {@inheritDoc AnnotatedConstruct}
|
|
*
|
|
* <p>Note that any annotations returned by this method are
|
|
* declaration annotations.
|
|
*
|
|
* @since 1.8
|
|
*/
|
|
@Override
|
|
<A extends Annotation> A[] getAnnotationsByType(Class<A> annotationType);
|
|
|
|
/**
|
|
* 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);
|
|
}
|