public interface Elements
Compatibility Note: Methods may be added to this interface in future releases of the platform.
Modifier and Type | Interface | Description |
---|---|---|
static enum |
Elements.Origin |
The origin of an element or other language model item. |
Modifier and Type | Method | Description |
---|---|---|
List |
getAllAnnotationMirrors |
Returns all annotations present on an element, whether directly present or present via inheritance. |
List |
getAllMembers |
Returns all members of a type element, whether inherited or declared directly. |
default Set |
getAllModuleElements() |
Returns all module elements in the current environment. |
default Set |
getAllPackageElements |
Returns all package elements with the given canonical name. |
default Set |
getAllTypeElements |
Returns all type elements with the given canonical name. |
Name |
getBinaryName |
Returns the binary name of a type element. |
String |
getConstantExpression |
Returns the text of a constant expression representing a primitive value or a string. |
String |
getDocComment |
Returns the text of the documentation ("Javadoc") comment of an element. |
Map |
getElementValuesWithDefaults |
Returns the values of an annotation's elements, including defaults. |
default JavaFileObject |
getFileObjectOf |
Returns the file object for this element or null if there is no such file object. |
default ModuleElement |
getModuleElement |
Returns a module element given its fully qualified name. |
default ModuleElement |
getModuleOf |
Returns the module of an element. |
Name |
getName |
Returns a name with the same sequence of characters as the argument. |
default Elements.Origin |
getOrigin |
Returns the origin of the given annotation mirror. |
default Elements.Origin |
getOrigin |
Returns the origin of the given element. |
default Elements.Origin |
getOrigin |
Returns the origin of the given module directive. |
default TypeElement |
getOutermostTypeElement |
Returns the outermost type element an element is contained in if such a containing element exists; otherwise returns
null . |
PackageElement |
getPackageElement |
Returns a package given its fully qualified name if the package is uniquely determinable in the environment. |
default PackageElement |
getPackageElement |
Returns a package given its fully qualified name, as seen from the given module. |
PackageElement |
getPackageOf |
Returns the package of an element. |
TypeElement |
getTypeElement |
Returns a type element given its canonical name if the type element is uniquely determinable in the environment. |
default TypeElement |
getTypeElement |
Returns a type element given its canonical name, as seen from the given module. |
boolean |
hides |
Tests whether one type, method, or field hides another. |
default boolean |
isAutomaticModule |
Returns true if the module element is an automatic module, false otherwise. |
default boolean |
isBridge |
Returns true if the executable element is a bridge method, false otherwise. |
default boolean |
isCanonicalConstructor |
Returns true if the executable element can be determined to be a canonical constructor of a record,
false otherwise. |
default boolean |
isCompactConstructor |
Returns true if the executable element can be determined to be a compact constructor of a record,
false otherwise. |
boolean |
isDeprecated |
Returns true if the element is deprecated, false otherwise. |
boolean |
isFunctionalInterface |
Returns true if the type element is a functional interface, false otherwise. |
boolean |
overrides |
Tests whether one method, as a member of a given class or interface, overrides another method. |
void |
printElements |
Prints a representation of the elements to the given writer in the specified order. |
default RecordComponentElement |
recordComponentFor |
Returns the record component for the given accessor. |
PackageElement getPackageElement(CharSequence name)
getPackageElement(ModuleElement, CharSequence)
, where the provided ModuleSymbol is any root module, all modules
for observable packages with the given name null
is returned.name
- fully qualified package name, or an empty string for an unnamed packagenull
if no package can be uniquely determined.default PackageElement getPackageElement(ModuleElement module, CharSequence name)
null
.module
- module relative to which the lookup should happenname
- fully qualified package name, or an empty string for an unnamed packagenull
if it cannot be founddefault Set<? extends PackageElement> getAllPackageElements(CharSequence name)
getAllModuleElements
and stores the result. If the set of modules is empty, getPackageElement(name)
is called passing through the name argument. If
getPackageElement(name)
is null
, an empty set of package elements is returned; otherwise, a single-element set with the found package element is returned. If the set of modules is nonempty, the modules are iterated over and any non-null
results of getPackageElement(module, name)
are accumulated into a set. The set is then returned.name
- the canonical nameTypeElement getTypeElement(CharSequence name)
getTypeElement(ModuleElement, CharSequence)
, where the provided ModuleSymbol is any root module, all modules
for observable type elements with the given name null
is returned.name
- the canonical namenull
if no type element can be uniquely determined.default TypeElement getTypeElement(ModuleElement module, CharSequence name)
null
.module
- module relative to which the lookup should happenname
- the canonical namenull
if it cannot be founddefault Set<? extends TypeElement> getAllTypeElements(CharSequence name)
getAllModuleElements
and stores the result. If the set of modules is empty, getTypeElement(name)
is called passing through the name argument. If
getTypeElement(name)
is null
, an empty set of type elements is returned; otherwise, a single-element set with the found type element is returned. If the set of modules is nonempty, the modules are iterated over and any non-null
results of getTypeElement(module, name)
are accumulated into a set. The set is then returned.name
- the canonical namedefault ModuleElement getModuleElement(CharSequence name)
null
is returned. One situation where a module cannot be found is if the environment does not include modules, such as an annotation processing environment configured for a source version without modules.null
.name
- the name, or an empty string for an unnamed modulenull
if it cannot be founddefault Set<? extends ModuleElement> getAllModuleElements()
Map<? extends ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(AnnotationMirror a)
a
- annotation to examineString getDocComment(Element e)
A documentation comment of an element is a comment that begins with "/**
", ends with a separate "*/
", and immediately precedes the element, ignoring white space. Therefore, a documentation comment contains at least three "*
" characters. The text returned for the documentation comment is a processed form of the comment as it appears in source code. The leading "/**
" and trailing "*/
" are removed. For lines of the comment starting after the initial "/**
", leading white space characters are discarded as are any consecutive "*
" characters appearing after the white space or starting the line. The processed lines are then concatenated together (including line terminators) and returned.
e
- the element being examinednull
if there is noneboolean isDeprecated(Element e)
true
if the element is deprecated, false
otherwise.e
- the element being examinedtrue
if the element is deprecated, false
otherwisedefault Elements.Origin getOrigin(Element e)
Note that if this method returns EXPLICIT
and the element was created from a class file, then the element may not, in fact, correspond to an explicitly declared construct in source code. This is due to limitations of the fidelity of the class file format in preserving information from source code. For example, at least some versions of the class file format do not preserve whether a constructor was explicitly declared by the programmer or was implicitly declared as the default constructor.
EXPLICIT
.e
- the element being examineddefault Elements.Origin getOrigin(AnnotatedConstruct c, AnnotationMirror a)
Note that if this method returns EXPLICIT
and the annotation mirror was created from a class file, then the element may not, in fact, correspond to an explicitly declared construct in source code. This is due to limitations of the fidelity of the class file format in preserving information from source code. For example, at least some versions of the class file format do not preserve whether an annotation was explicitly declared by the programmer or was implicitly declared as a container annotation.
EXPLICIT
.c
- the construct the annotation mirror modifiesa
- the annotation mirror being examineddefault Elements.Origin getOrigin(ModuleElement m, ModuleElement.Directive directive)
Note that if this method returns EXPLICIT
and the module directive was created from a class file, then the module directive may not, in fact, correspond to an explicitly declared construct in source code. This is due to limitations of the fidelity of the class file format in preserving information from source code. For example, at least some versions of the class file format do not preserve whether a uses
directive was explicitly declared by the programmer or was added as a synthetic construct.
Note that an implementation may not be able to reliably determine the origin status of the directive if the directive is created from a class file due to limitations of the fidelity of the class file format in preserving information from source code.
EXPLICIT
.m
- the module of the directivedirective
- the module directive being examineddefault boolean isBridge(ExecutableElement e)
true
if the executable element is a bridge method, false
otherwise.false
.e
- the executable being examinedtrue
if the executable element is a bridge method, false
otherwiseName getBinaryName(TypeElement type)
type
- the type element being examinedPackageElement getPackageOf(Element e)
null
. The package of a top-level class or interface is its enclosing package. Otherwise, the package of an element is equal to the package of the enclosing element.e
- the element being examineddefault ModuleElement getModuleOf(Element e)
null
, null
is returned for the package's module. (One situation where a package may have a null
module is if the environment does not include modules, such as an annotation processing environment configured for a source version without modules.) Otherwise, the module of an element is equal to the module of the package of the element.null
.e
- the element being examinedList<? extends Element> getAllMembers(TypeElement type)
ElementFilter
.type
- the type being examineddefault TypeElement getOutermostTypeElement(Element e)
null
. Modules and packages do not have a containing type element and therefore null
is returned for those kinds of elements. A top-level class or interface is its own outermost type element.PACKAGE
,
MODULE
, and OTHER
, null
is returned. For elements of other kinds, the element is examined to see if it is a top-level class or interface. If so, that element is returned; otherwise, the enclosing element chain is followed until a top-level class or interface is found. The element for the eventual top-level class or interface is returned.e
- the element being examined
null
List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e)
Note that any annotations returned by this method are declaration annotations.
e
- the element being examinedboolean hides(Element hider, Element hidden)
hider
- the first elementhidden
- the second elementtrue
if and only if the first element hides the secondboolean overrides(ExecutableElement overrider, ExecutableElement overridden, TypeElement type)
In the simplest and most typical usage, the value of the type
parameter will simply be the class or interface directly enclosing overrider
(the possibly-overriding method). For example, suppose m1
represents the method String.hashCode
and m2
represents
Object.hashCode
. We can then ask whether m1
overrides m2
within the class String
(it does):
assert elements.overrides(m1, m2,
elements.getTypeElement("java.lang.String"));
A more interesting case can be illustrated by the following example in which a method in class A
does not override a like-named method in interface B
: When viewed as a member of a third classclass A { public void m() {} }
interface B { void m(); }
...
m1 = ...; // A.m
m2 = ...; // B.m
assert ! elements.overrides(m1, m2, elements.getTypeElement("A"));
C
, however, the method in A
does override the one in B
: class C extends A implements B {}
...
assert elements.overrides(m1, m2, elements.getTypeElement("C"));
overrider
- the first method, possible overrideroverridden
- the second method, possibly being overriddentype
- the class or interface of which the first method is a membertrue
if and only if the first method overrides the secondString getConstantExpression(Object value)
value
- a primitive value or stringIllegalArgumentException
- if the argument is not a primitive value or stringvoid printElements(Writer w, Element... elements)
w
- the writer to print the output toelements
- the elements to printName getName(CharSequence cs)
cs
- the character sequence to return as a nameboolean isFunctionalInterface(TypeElement type)
true
if the type element is a functional interface, false
otherwise.type
- the type element being examinedtrue
if the type element is a functional interface, false
otherwisedefault boolean isAutomaticModule(ModuleElement module)
true
if the module element is an automatic module, false
otherwise.
false
.module
- the module element being examinedtrue
if the module element is an automatic module, false
otherwisedefault RecordComponentElement recordComponentFor(ExecutableElement accessor)
null
if the given method is not a record component accessor.RECORD
if that is the case, then all the record components on the accessor's enclosing element are retrieved by invoking ElementFilter.recordComponentsIn(Iterable)
. If the accessor of at least one of the record components retrieved happen to be equal to the accessor passed as a parameter to this method, then that record component is returned, in any other case null
is returned.accessor
- the method for which the record component should be found.null
if the given method is not a record component accessordefault boolean isCanonicalConstructor(ExecutableElement e)
true
if the executable element can be determined to be a canonical constructor of a record,
false
otherwise. Note that in some cases there may be insufficient information to determine if a constructor is a canonical constructor, such as if the executable element is built backed by a class file. In such cases, false
is returned.false
.e
- the executable being examinedtrue
if the executable element can be determined to be a canonical constructor of a record,
false
otherwisedefault boolean isCompactConstructor(ExecutableElement e)
true
if the executable element can be determined to be a compact constructor of a record,
false
otherwise. By definition, a compact constructor is also a canonical constructor. Note that in some cases there may be insufficient information to determine if a constructor is a compact constructor, such as if the executable element is built backed by a class file. In such cases, false
is returned.false
.e
- the executable being examinedtrue
if the executable element can be determined to be a compact constructor of a record,
false
otherwisedefault JavaFileObject getFileObjectOf(Element e)
null
if there is no such file object. The returned file object is for the reference representation of the information used to construct the element. For example, if during compilation or annotation processing, a source file for class Foo
is compiled into a class file, the file object returned for the element representing Foo
would be for the source file and not for the class file.
An implementation may choose to not support the functionality of this method, in which case UnsupportedOperationException
is thrown.
In the context of annotation processing, a non-null
value is returned if the element was included as part of the initial inputs or the containing file was created during the run of the annotation processing tool. Otherwise, a
null
may be returned. In annotation processing, if a class file is created, that class file can serve as the reference representation for elements.
If it has a file object, the file object for a package will be a package-info
file. A package may exist and not have any package-info
file even if the package is (implicitly) created during an annotation processing run from the creation of source or class files in that package. An unnamed package will have a null
file since it cannot be declared in a compilation unit.
If it has a file object, the file object for a module will be a module-info
file. An unnamed module will have a
null
file since it cannot be declared in a compilation unit. An automatic module will have a null
file since it is implicitly declared.
If it has a file object, the file object for a top-level public
class or interface will be a source or class file corresponding to that class or interface. In this case, typically the leading portion of the name of the file will match the name of the class or interface. A single compilation unit can define multiple top-level classes and interfaces, such as a primary public
class or interfaces whose name corresponds to the file name and one or more auxiliary classes or interfaces whose names do not correspond to the file name. If a source file is providing the reference representation of an auxiliary class or interface, the file for the primary class is returned. (An auxiliary class or interface can also be defined in a package-info
source file, in which case the file for the package-info
file is returned.) If a class file is providing the reference representation of an auxiliary class or interface, the separate class file for the auxiliary class is returned.
For a nested class or interface, if it has a file object:
For other lexically enclosed elements, such as variables, methods, and constructors, if they have a file object, the file object will be the object associated with the enclosing element of the lexically enclosed element.
UnsupportedOperationException
.e
- the element to find a file object fornull
if there is no such file objectUnsupportedOperationException
- if this functionality is not supported
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.compiler/javax/lang/model/util/Elements.html