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()`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `Elements.Origin` | The origin of an element or other language model item.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `List<? extends AnnotationMirror>` | `getAllAnnotationMirrors​(Element e)` | Returns all annotations present on an element, whether directly present or present via inheritance.
    `List<? extends Element>` | `getAllMembers​(TypeElement type)` | Returns all members of a type element, whether inherited or declared directly.
    `default Set<? extends ModuleElement>` | `getAllModuleElements()` | Returns all module elements in the current environment.
    `default Set<? extends PackageElement>` | `getAllPackageElements​(CharSequence name)` | Returns all package elements with the given canonical name.
    `default Set<? extends TypeElement>` | `getAllTypeElements​(CharSequence name)` | Returns all type elements with the given canonical name.
    `Name` | `getBinaryName​(TypeElement type)` | Returns the binary name of a type element.
    `String` | `getConstantExpression​(Object value)` | Returns the text of a constant expression representing a primitive value or a string.
    `String` | `getDocComment​(Element e)` | Returns the text of the documentation ("Javadoc") comment of an element.
    `Map<? extends ExecutableElement,​? extends AnnotationValue>` | `getElementValuesWithDefaults​(AnnotationMirror a)` | Returns the values of an annotation's elements, including defaults.
    `default ModuleElement` | `getModuleElement​(CharSequence name)` | Returns a module element given its fully qualified name.
    `default ModuleElement` | `getModuleOf​(Element type)` | Returns the module of an element.
    `Name` | `getName​(CharSequence cs)` | Return a name with the same sequence of characters as the argument.
    `default Elements.Origin` | `getOrigin​(AnnotatedConstruct c, AnnotationMirror a)` | Returns the origin of the given annotation mirror.
    `default Elements.Origin` | `getOrigin​(Element e)` | Returns the origin of the given element.
    `default Elements.Origin` | `getOrigin​(ModuleElement m, ModuleElement.Directive directive)` | Returns the origin of the given module directive.
    `PackageElement` | `getPackageElement​(CharSequence name)` | Returns a package given its fully qualified name if the package is unique in the environment.
    `default PackageElement` | `getPackageElement​(ModuleElement module, CharSequence name)` | Returns a package given its fully qualified name, as seen from the given module.
    `PackageElement` | `getPackageOf​(Element type)` | Returns the package of an element.
    `TypeElement` | `getTypeElement​(CharSequence name)` | Returns a type element given its canonical name if the type element is unique in the environment.
    `default TypeElement` | `getTypeElement​(ModuleElement module, CharSequence name)` | Returns a type element given its canonical name, as seen from the given module.
    `boolean` | `hides​(Element hider, Element hidden)` | Tests whether one type, method, or field hides another.
    `default boolean` | `isBridge​(ExecutableElement e)` | Returns `true` if the executable element is a bridge method, `false` otherwise.
    `boolean` | `isDeprecated​(Element e)` | Returns `true` if the element is deprecated, `false` otherwise.
    `boolean` | `isFunctionalInterface​(TypeElement type)` | Returns `true` if the type element is a functional interface, `false` otherwise.
    `boolean` | `overrides​(ExecutableElement overrider, ExecutableElement overridden, TypeElement type)` | Tests whether one method, as a member of a given type, overrides another method.
    `void` | `printElements​(Writer w, Element... elements)` | Prints a representation of the elements to the given writer in the specified order.

- - ### Method Detail

    - #### getPackageElement

          PackageElement getPackageElement​(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,
                                                   CharSequence name)

      Returns a package given its fully qualified name, as seen from the given module.
      Implementation Requirements:
        The default implementation of this method returns `null`.
      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 Set<? extends PackageElement> getAllPackageElements​(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.
      Implementation Requirements:
        The default implementation of this method calls `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.
      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​(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,
                                             CharSequence name)

      Returns a type element given its canonical name, as seen from the given module.
      Implementation Requirements:
        The default implementation of this method returns `null`.
      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 Set<? extends TypeElement> getAllTypeElements​(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.
      Implementation Requirements:
        The default implementation of this method calls `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.
      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​(CharSequence name)

      Returns a module element given its fully qualified name. If the named 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.
      Implementation Requirements:
        The default implementation of this method returns `null`.
      Parameters:
        `name` - the name
      Returns:
        the named module element, or `null` if it cannot be found
      Since:
        9
      See Also:
        `getAllModuleElements()`

    - #### getAllModuleElements

          default 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.
      Implementation Requirements:
        The default implementation of this method returns an empty set.
      Returns:
        the known module elements, or an empty set if there are no modules
      Since:
        9
      See Also:
        `getModuleElement(CharSequence)`

    - #### getElementValuesWithDefaults

          Map<? extends ExecutableElement,​? extends AnnotationValue> getElementValuesWithDefaults​(AnnotationMirror a)

      Returns the values of an annotation's elements, including defaults.
      Parameters:
        `a` - annotation to examine
      Returns:
        the values of the annotation's elements, including defaults
      See Also:
        `AnnotationMirror.getElementValues()`

    - #### getDocComment

          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
      See The Java™ Language Specification:
        3.6 White Space

    - #### 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.

      Implementation Requirements:
        The default implementation of this method returns `EXPLICIT`.
      Parameters:
        `e` - the element being examined
      Returns:
        the origin of the given element
      Since:
        9

    - #### getOrigin

          default Elements.Origin getOrigin​(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.

      Implementation Requirements:
        The default implementation of this method returns `EXPLICIT`.
      Parameters:
        `c` - the construct the annotation mirror modifies
        `a` - the annotation mirror being examined
      Returns:
        the origin of the given annotation mirror
      Since:
        9
      See The Java™ Language Specification:
        9.6.3 Repeatable Annotation Types, 9.7.5 Multiple Annotations of the Same Type

    - #### 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.

      Implementation Requirements:
        The default implementation of this method returns `EXPLICIT`.
      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.
      Implementation Requirements:
        The default implementation of this method returns `false`.
      Parameters:
        `e` - the executable being examined
      Returns:
        `true` if the executable element is a bridge method, `false` otherwise
      Since:
        9

    - #### getBinaryName

          Name getBinaryName​(TypeElement type)

      Returns the binary name of a type element.
      Parameters:
        `type` - the type element being examined
      Returns:
        the binary name
      See Also:
        `TypeElement.getQualifiedName()`
      See The Java™ Language Specification:
        13.1 The Form of a Binary

    - #### getPackageOf

          PackageElement getPackageOf​(Element type)

      Returns the package of an element. The package of a package is itself.
      Parameters:
        `type` - the element being examined
      Returns:
        the package of an element

    - #### getModuleOf

          default ModuleElement getModuleOf​(Element type)

      Returns the module of an element. The module of a module is itself. If there is no module for the element, null is returned. One situation where there is no module for an element is if the environment does not include modules, such as an annotation processing environment configured for a source version without modules.
      Implementation Requirements:
        The default implementation of this method returns `null`.
      Parameters:
        `type` - the element being examined
      Returns:
        the module of an element
      Since:
        9

    - #### getAllMembers

          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.
      API Note:
        Elements of certain kinds can be isolated using methods in `ElementFilter`.
      Parameters:
        `type` - the type being examined
      Returns:
        all members of the type
      See Also:
        `Element.getEnclosedElements()`

    - #### getAllAnnotationMirrors

          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
      See The Java™ Language Specification:
        8.4.8 Inheritance, Overriding, and Hiding, 9.4.1 Inheritance and Overriding

    - #### getConstantExpression

          String getConstantExpression​(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:
        `IllegalArgumentException` - if the argument is not a primitive value or string
      See Also:
        `VariableElement.getConstantValue()`

    - #### printElements

          void printElements​(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​(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
      See The Java™ Language Specification:
        9.8 Functional Interfaces