javax.lang.model.element.Element Maven / Gradle / Ivy
Show all versions of jx Show documentation
/*
* Copyright (C) 2021 ZeoFlow SRL
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package javax.lang.model.element;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.ElementFilter;
import javax.lang.model.AnnotatedConstruct;
import javax.lang.model.util.Elements;
import java.lang.annotation.Annotation;
import java.util.List;
import java.util.Set;
import javax.lang.model.util.Types;
/**
* 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).
*
* 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.
*
*
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 not 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 extends AnnotatedConstruct
{
/**
* Returns the type defined by this element.
*
*
A generic element defines a family of types, not just one.
* If this is a generic element, a prototypical 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},
* the parameterized type {@code C} is returned.
* The {@link javax.lang.model.util.Types} utility interface has more general methods
* for obtaining the full range of types defined by an element.
*
* @return the type defined by this element
*
* @see Types
*/
TypeMirror asType();
/**
* Returns the {@code kind} of this element.
*
* @return the kind of this element
*/
ElementKind getKind();
/**
* 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 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} 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 }" is returned. If it
* represents a {@linkplain ExecutableElement#getSimpleName static
* initializer}, the name "{@code }" 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.
*
* - If this element is one whose declaration is lexically enclosed
* immediately within the declaration of another element, that other
* element is returned.
*
*
- If this is a {@linkplain TypeElement#getEnclosingElement
* top-level type}, its package is returned.
*
*
- If this is a {@linkplain
* PackageElement#getEnclosingElement package}, {@code null} is
* returned.
*
*
- If this is a {@linkplain
* TypeParameterElement#getEnclosingElement type parameter},
* {@linkplain TypeParameterElement#getGenericElement the
* generic element} of the type parameter is returned.
*
*
- If this is a {@linkplain
* VariableElement#getEnclosingElement method or constructor
* parameter}, {@linkplain ExecutableElement the executable
* element} which declares the parameter is returned.
*
*
*
* @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.
*
*
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
*/
List getEnclosedElements();
/**
* Returns {@code true} if the argument represents the same
* element as {@code this}, or {@code false} otherwise.
*
*
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
* not 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
*/
@Override
boolean equals(Object obj);
/**
* Obeys the general contract of {@link Object#hashCode Object.hashCode}.
*
* @see #equals
*/
@Override
int hashCode();
/**
* {@inheritDoc}
*
*
To get inherited annotations as well, use {@link
* Elements#getAllAnnotationMirrors(Element)
* getAllAnnotationMirrors}.
*
* @since 1.6
*/
@Override
List getAnnotationMirrors();
/**
* {@inheritDoc}
*
* @since 1.6
*/
@Override
A getAnnotation(Class annotationType);
/**
* Applies a visitor to this element.
*
* @param the return type of the visitor's methods
* @param 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 accept(ElementVisitor v, P p);
}