Module java.compiler
Package javax.lang.model.util

Interface Elements

  • public interface Elements
    Utility methods for operating on program elements.

    Compatibility Note: Methods may be added to this interface in future releases of the platform.

    Since:
    1.6
    See Also:
    ProcessingEnvironment.getElementUtils()

    • Method Detail

      • getPackageElement

        PackageElement getPackageElement​(java.lang.CharSequence name)
        Returns a package given its fully qualified name if the package is unique in the environment. If running with modules, all modules in the modules graph are searched for matching packages.
        Parameters:
        name - fully qualified package name, or an empty string for an unnamed package
        Returns:
        the specified package, or null if it cannot be uniquely found

      • getPackageElement

        default PackageElement getPackageElement​(ModuleElement module,
                                         java.lang.CharSequence name)
        Returns a package given its fully qualified name, as seen from the given module.
        Parameters:
        name - fully qualified package name, or an empty string for an unnamed package
        module - module relative to which the lookup should happen
        Returns:
        the specified package, or null if it cannot be found
        Since:
        9
        See Also:
        getAllPackageElements(java.lang.CharSequence)

      • getAllPackageElements

        default java.util.Set<? extends PackageElement> getAllPackageElements​(java.lang.CharSequence name)
        Returns all package elements with the given canonical name. There may be more than one package element with the same canonical name if the package elements are in different modules.
        Parameters:
        name - the canonical name
        Returns:
        the package elements, or an empty set if no package with the name can be found
        Since:
        9
        See Also:
        getPackageElement(ModuleElement, CharSequence)

      • getTypeElement

        TypeElement getTypeElement​(java.lang.CharSequence name)
        Returns a type element given its canonical name if the type element is unique in the environment. If running with modules, all modules in the modules graph are searched for matching type elements.
        Parameters:
        name - the canonical name
        Returns:
        the named type element, or null if it cannot be uniquely found

      • getTypeElement

        default TypeElement getTypeElement​(ModuleElement module,
                                   java.lang.CharSequence name)
        Returns a type element given its canonical name, as seen from the given module.
        Parameters:
        name - the canonical name
        module - module relative to which the lookup should happen
        Returns:
        the named type element, or null if it cannot be found
        Since:
        9
        See Also:
        getAllTypeElements(java.lang.CharSequence)

      • getAllTypeElements

        default java.util.Set<? extends TypeElement> getAllTypeElements​(java.lang.CharSequence name)
        Returns all type elements with the given canonical name. There may be more than one type element with the same canonical name if the type elements are in different modules.
        Parameters:
        name - the canonical name
        Returns:
        the type elements, or an empty set if no type with the name can be found
        Since:
        9
        See Also:
        getTypeElement(ModuleElement, CharSequence)

      • getModuleElement

        default ModuleElement getModuleElement​(java.lang.CharSequence name)
        Returns a module element given its fully qualified name. If the requested module cannot be found, 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.
        Parameters:
        name - the name, or an empty string for an unnamed module
        Returns:
        the named module element, or null if it cannot be found
        Since:
        9
        See Also:
        getAllModuleElements()

      • getAllModuleElements

        default java.util.Set<? extends ModuleElement> getAllModuleElements()
        Returns all module elements in the current environment. If no modules are present, an empty set is returned. One situation where no modules are present occurs when the environment does not include modules, such as an annotation processing environment configured for a source version without modules.
        Returns:
        the known module elements, or an empty set if there are no modules
        Since:
        9
        See Also:
        getModuleElement(CharSequence)

      • getDocComment

        java.lang.String getDocComment​(Element e)
        Returns the text of the documentation ("Javadoc") comment of an element.

        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.

        Parameters:
        e - the element being examined
        Returns:
        the documentation comment of the element, or null if there is none

      • isDeprecated

        boolean isDeprecated​(Element e)
        Returns true if the element is deprecated, false otherwise.
        Parameters:
        e - the element being examined
        Returns:
        true if the element is deprecated, false otherwise

      • getOrigin

        default Elements.Origin getOrigin​(Element e)
        Returns the origin of the given element.

        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.

        Parameters:
        e - the element being examined
        Returns:
        the origin of the given element
        Since:
        9

      • getOrigin

        default Elements.Origin getOrigin​(javax.lang.model.AnnotatedConstruct c,
                                  AnnotationMirror a)
        Returns the origin of the given annotation mirror. An annotation mirror is mandated if it is an implicitly declared container annotation used to hold repeated annotations of a repeatable annotation type.

        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.

        Parameters:
        c - the construct the annotation mirror modifies
        a - the annotation mirror being examined
        Returns:
        the origin of the given annotation mirror
        Since:
        9

      • getOrigin

        default Elements.Origin getOrigin​(ModuleElement m,
                                  ModuleElement.Directive directive)
        Returns the origin of the given module 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.

        Parameters:
        m - the module of the directive
        directive - the module directive being examined
        Returns:
        the origin of the given directive
        Since:
        9

      • isBridge

        default boolean isBridge​(ExecutableElement e)
        Returns true if the executable element is a bridge method, false otherwise.
        Parameters:
        e - the executable being examined
        Returns:
        true if the executable element is a bridge method, false otherwise
        Since:
        9

      • getPackageOf

        PackageElement getPackageOf​(Element e)
        Returns the package of an element. The package of a package is itself. The package of a module is null. The package of a top-level type is its enclosing package. Otherwise, the package of an element is equal to the package of the enclosing element.
        Parameters:
        e - the element being examined
        Returns:
        the package of an element

      • getModuleOf

        default ModuleElement getModuleOf​(Element e)
        Returns the module of an element. The module of a module is itself. If a package has a module as its enclosing element, that module is the module of the package. If the enclosing element of a package is 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.
        Parameters:
        e - the element being examined
        Returns:
        the module of an element
        Since:
        9

      • getAllMembers

        java.util.List<? extends Element> getAllMembers​(TypeElement type)
        Returns all members of a type element, whether inherited or declared directly. For a class the result also includes its constructors, but not local or anonymous classes.
        Parameters:
        type - the type being examined
        Returns:
        all members of the type
        See Also:
        Element.getEnclosedElements()

      • getAllAnnotationMirrors

        java.util.List<? extends AnnotationMirror> getAllAnnotationMirrors​(Element e)
        Returns all annotations present on an element, whether directly present or present via inheritance.
        Parameters:
        e - the element being examined
        Returns:
        all annotations of the element
        See Also:
        Element.getAnnotationMirrors(), AnnotatedConstruct

      • hides

        boolean hides​(Element hider,
              Element hidden)
        Tests whether one type, method, or field hides another.
        Parameters:
        hider - the first element
        hidden - the second element
        Returns:
        true if and only if the first element hides the second

      • overrides

        boolean overrides​(ExecutableElement overrider,
                  ExecutableElement overridden,
                  TypeElement type)
        Tests whether one method, as a member of a given type, overrides another method. When a non-abstract method overrides an abstract one, the former is also said to implement the latter.

        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 type A does not override a like-named method in type B:
        class A { public void m() {} }
        interface B { void m(); }
        ...
        m1 = ...; // A.m
        m2 = ...; // B.m
        assert ! elements.overrides(m1, m2, elements.getTypeElement("A"));
        When viewed as a member of a third type 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"));
        Parameters:
        overrider - the first method, possible overrider
        overridden - the second method, possibly being overridden
        type - the type of which the first method is a member
        Returns:
        true if and only if the first method overrides the second

      • getConstantExpression

        java.lang.String getConstantExpression​(java.lang.Object value)
        Returns the text of a constant expression representing a primitive value or a string. The text returned is in a form suitable for representing the value in source code.
        Parameters:
        value - a primitive value or string
        Returns:
        the text of a constant expression
        Throws:
        java.lang.IllegalArgumentException - if the argument is not a primitive value or string
        See Also:
        VariableElement.getConstantValue()

      • printElements

        void printElements​(java.io.Writer w,
                   Element... elements)
        Prints a representation of the elements to the given writer in the specified order. The main purpose of this method is for diagnostics. The exact format of the output is not specified and is subject to change.
        Parameters:
        w - the writer to print the output to
        elements - the elements to print

      • getName

        Name getName​(java.lang.CharSequence cs)
        Return a name with the same sequence of characters as the argument.
        Parameters:
        cs - the character sequence to return as a name
        Returns:
        a name with the same sequence of characters as the argument

      • isFunctionalInterface

        boolean isFunctionalInterface​(TypeElement type)
        Returns true if the type element is a functional interface, false otherwise.
        Parameters:
        type - the type element being examined
        Returns:
        true if the element is a functional interface, false otherwise
        Since:
        1.8

      • recordComponentFor

        default RecordComponentElement recordComponentFor​(ExecutableElement accessor)
        Returns the record component for the given accessor. Returns null if the given method is not a record component accessor.
        Parameters:
        accessor - the method for which the record component should be found.
        Returns:
        the record component, or null if the given method is not an record component accessor
        Since:
        14