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

Interface Elements

public interface Elements
操作程序元素的实用方法。

兼容性注意： 未来版本的平台可能会添加方法到此接口中。

自版本:
1.6
参见:

  • Method Details

    • getPackageElement

      PackageElement getPackageElement(CharSequence name)
      如果在环境中可以唯一确定包，则返回给定完全限定名称的包。如果运行时存在模块，则按以下两阶段过程搜索给定名称的包： 如果此过程导致列表中只有一个元素，则返回该单个元素，否则返回null。
      参数:
      name - 完全限定包名称，或空字符串表示未命名包
      返回:
      指定的包，如果无法唯一确定包则返回null。

    • getPackageElement

      default PackageElement getPackageElement(ModuleElement module, CharSequence name)
      返回给定模块中从给定完全限定名称看到的包。
      实现要求:
      此方法的默认实现返回null。
      参数:
      module - 应进行查找的相对模块
      name - 完全限定包名称，或空字符串表示未命名包
      返回:
      指定的包，如果找不到则返回null。
      自版本:
      9
      参见:

    • getAllPackageElements

      default Set<? extends PackageElement> getAllPackageElements(CharSequence name)
      返回具有给定规范名称的所有包元素。如果包元素位于不同模块中，则可能存在具有相同规范名称的多个包元素。
      实现要求:
      此方法的默认实现调用getAllModuleElements并存储结果。如果模块集为空，则调用getPackageElement(name)，传递名称参数。如果getPackageElement(name)为null，则返回一个空的包元素集；否则，返回一个包含找到的包元素的单元素集。如果模块集非空，则迭代模块，并将getPackageElement(module, name)的任何非null结果累积到一个集合中。然后返回该集合。
      参数:
      name - 规范名称
      返回:
      包元素，如果找不到具有该名称的包则返回空集
      自版本:
      9
      参见:

    • getTypeElement

      TypeElement getTypeElement(CharSequence name)
      如果在环境中可以唯一确定类型元素，则返回给定规范名称的类型元素。如果运行时存在模块，则按以下两阶段过程搜索给定名称的类型元素： 如果此过程导致列表中只有一个元素，则返回该单个元素，否则返回null。
      参数:
      name - 规范名称
      返回:
      具有指定名称的类型元素，如果无法唯一确定类型元素则返回null。

    • getTypeElement

      default TypeElement getTypeElement(ModuleElement module, CharSequence name)
      返回给定模块中从给定规范名称看到的类型元素。
      实现要求:
      此方法的默认实现返回null。
      参数:
      module - 应进行查找的相对模块
      name - 规范名称
      返回:
      具有指定名称的类型元素，如果找不到则返回null。
      自版本:
      9
      参见:

    • getAllTypeElements

      default Set<? extends TypeElement> getAllTypeElements(CharSequence name)
      返回具有给定规范名称的所有类型元素。如果类型元素位于不同模块中，则可能存在具有相同规范名称的多个类型元素。
      实现要求:
      此方法的默认实现调用getAllModuleElements并存储结果。如果模块集为空，则调用getTypeElement(name)，传递名称参数。如果getTypeElement(name)为null，则返回一个空的类型元素集；否则，返回一个包含找到的类型元素的单元素集。如果模块集非空，则迭代模块，并将getTypeElement(module, name)的任何非null结果累积到一个集合中。然后返回该集合。
      参数:
      name - 规范名称
      返回:
      类型元素，如果找不到具有该名称的类型则返回空集
      自版本:
      9
      参见:

    • getModuleElement

      default ModuleElement getModuleElement(CharSequence name)
      返回给定完全限定名称的模块元素。如果无法找到请求的模块，则返回null。一个无法找到模块的情况是，如果环境不包括模块，例如配置为没有模块的源版本的注解处理环境。
      实现要求:
      此方法的默认实现返回null。
      参数:
      name - 名称，或者对于未命名模块为空字符串
      返回值:
      命名模块元素，如果找不到则返回null
      自 JDK 版本:
      9
      参见:

    • getAllModuleElements

      default Set<? extends ModuleElement> getAllModuleElements()
      返回当前环境中的所有模块元素。如果没有模块存在，则返回一个空集。没有模块存在的一种情况是当环境不包括模块时，例如配置为不包含模块的注解处理环境，如配置为没有模块的源版本。
      API 注释:
      当环境包括模块时，可能会返回命名模块和未命名模块。
      实现要求:
      此方法的默认实现返回一个空集。
      返回值:
      已知模块元素，如果没有模块则返回一个空集
      自 JDK 版本:
      9
      参见:

    • getElementValuesWithDefaults

      Map<? extends ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(AnnotationMirror a)
      返回注解元素的值，包括默认值。
      参数:
      a - 要检查的注解
      返回值:
      注解元素的值，包括默认值
      参见:

    • getDocComment

      String getDocComment(Element e)
      返回元素的文档（"Javadoc"）注释文本。

      元素的文档注释是以"/**"开头，以单独的"*/"结尾，并紧随元素之前的注释，忽略空格。因此，文档注释至少包含三个"*"字符。返回的文档注释文本是注释的处理形式，就像在源代码中出现的那样。去掉文档注释的开头"/**"和结尾"*/"。对于注释的行，从初始"/**"之后开始的行，去掉前导空格字符，以及在空格之后或行首出现的任何连续"*"字符。然后将处理后的行连接在一起（包括行终止符）并返回。

      参数:
      e - 要检查的元素
      返回值:
      元素的文档注释，如果没有则返回null
      参见 Java 语言规范:
      3.6 空格

    • isDeprecated

      boolean isDeprecated(Element e)
      如果元素已过时，则返回true，否则返回false。
      参数:
      e - 要检查的元素
      返回值:
      如果元素已过时，则返回true，否则返回false

    • getOrigin

      default Elements.Origin getOrigin(Element e)
      返回给定元素的来源。

      请注意，如果此方法返回EXPLICIT并且元素是从类文件创建的，则该元素实际上可能不对应于源代码中显式声明的构造。这是由于类文件格式在保留来自源代码的信息方面的准确性限制。例如，至少某些版本的类文件格式不保留程序员是否显式声明了构造函数或隐式声明为默认构造函数的信息。

      实现要求:
      此方法的默认实现返回EXPLICIT。
      参数:
      e - 要检查的元素
      返回值:
      给定元素的来源
      自 JDK 版本:
      9

    • getOrigin

      default Elements.Origin getOrigin(AnnotatedConstruct c, AnnotationMirror a)
      返回给定注解镜像的来源。如果注解镜像是用于保存可重复注解接口的重复注解的隐式声明的容器注解，则注解镜像是强制性的。

      请注意，如果此方法返回EXPLICIT并且注解镜像是从类文件创建的，则该元素实际上可能不对应于源代码中显式声明的构造。这是由于类文件格式在保留来自源代码的信息方面的准确性限制。例如，至少某些版本的类文件格式不保留程序员是否显式声明了注解或隐式声明为容器注解的信息。

      实现要求:
      此方法的默认实现返回EXPLICIT。
      参数:
      c - 注解镜像修改的构造
      a - 要检查的注解镜像
      返回值:
      给定注解镜像的来源
      参见 Java 语言规范:
      9.6.3 可重复注解接口
      9.7.5 相同接口的多个注解
      自 JDK 版本:
      9

    • getOrigin

      default Elements.Origin getOrigin(ModuleElement m, ModuleElement.Directive directive)
      返回给定模块指令的来源。

      请注意，如果此方法返回EXPLICIT并且模块指令是从类文件创建的，则该模块指令实际上可能不对应于源代码中显式声明的构造。这是由于类文件格式在保留来自源代码的信息方面的准确性限制。例如，至少某些版本的类文件格式不保留程序员是否显式声明了uses指令或作为合成构造添加的信息。

      请注意，如果由于类文件格式在保留来自源代码的信息方面的准确性限制，实现可能无法可靠地确定指令的来源状态，则无法从类文件创建指令。

      实现要求:
      此方法的默认实现返回EXPLICIT。
      参数:
      m - 指令的模块
      directive - 要检查的模块指令
      返回值:
      给定模块指令的来源
      自 JDK 版本:
      9

    • isBridge

      default boolean isBridge(ExecutableElement e)
      如果可执行元素是桥接方法，则返回true，否则返回false。
      实现要求:
      此方法的默认实现返回false。
      参数:
      e - 要检查的可执行元素
      返回值:
      如果可执行元素是桥接方法，则返回true，否则返回false
      自 JDK 版本:
      9

    • getBinaryName

      Name getBinaryName(TypeElement type)
      返回类型元素的二进制名称。
      参数:
      type - 要检查的类型元素
      返回值:
      类型元素的二进制名称
      参见 Java 语言规范:
      13.1 二进制形式
      参见:

    • getPackageOf

      PackageElement getPackageOf(Element e)
      返回元素的包。包的包是它本身。模块的包是null。顶层类或接口的包是其封装包。否则，元素的包等于封装元素的包。
      参数:
      e - 要检查的元素
      返回值:
      元素的包

    • getModuleOf

      default ModuleElement getModuleOf(Element e)
      返回元素的模块。模块的模块是它本身。如果包的封装元素是模块，则该模块是包的模块。如果包的封装元素是null，则对于包的模块返回null。（包可能具有null模块的一种情况是，如果环境不包括模块，例如配置为不包含模块的注解处理环境，如配置为没有模块的源版本。）否则，元素的模块等于元素的包的模块的模块。
      实现要求:
      此方法的默认实现返回null。
      参数:
      e - 要检查的元素
      返回值:
      元素的模块
      自 JDK 版本:
      9

    • getAllMembers

      List<? extends Element> getAllMembers(TypeElement type)
      返回类型元素的所有成员，无论是继承的还是直接声明的。对于类，结果还包括其构造函数，但不包括局部类或匿名类。
      API 注释:
      可以使用ElementFilter中的方法来隔离某些类型的元素。
      参数:
      type - 要检查的类型
      返回值:
      类型的所有成员
      参见:

    • getOutermostTypeElement

      default TypeElement getOutermostTypeElement(Element e)
      返回元素所包含的最外层类型元素（如果存在这样的包含元素）；否则返回null。模块和包不具有包含类型元素，因此对于这些类型的元素将返回null。顶层类或接口是其自身的最外层类型元素。
      实现要求：
      此方法的默认实现首先检查参数的类型。对于PACKAGE、MODULE和OTHER类型的元素，将返回null。对于其他类型的元素，将检查该元素是否为顶层类或接口。如果是，则返回该元素；否则，将遵循封闭元素链，直到找到顶层类或接口。返回最终顶层类或接口的元素。
      参数：
      e - 要检查的元素
      返回：
      元素所包含的最外层类型元素（如果存在这样的包含元素）；否则返回null
      自：
      18
      参见：

    • getAllAnnotationMirrors

      List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e)
      返回元素上存在的所有注解，无论是直接存在还是通过继承存在。

      请注意，此方法返回的任何注解都是声明注解。

      参数：
      e - 要检查的元素
      返回：
      元素的所有注解
      参见：

    • hides

      boolean hides(Element hider, Element hidden)
      测试一个类型、方法或字段是否隐藏另一个。
      参数：
      hider - 第一个元素
      hidden - 第二个元素
      返回：
      如果第一个元素隐藏第二个元素，则返回true
      参见《Java语言规范》：
      8.4.8 继承、覆盖和隐藏

    • overrides

      boolean overrides(ExecutableElement overrider, ExecutableElement overridden, TypeElement type)
      测试一个方法作为给定类或接口的成员是否覆盖另一个方法。当一个非抽象方法覆盖一个抽象方法时，前者也被称为实现后者。如JLS 8.4.8.1所示，一个方法不会覆盖自身。覆盖关系是非自反的。

      在最简单和最典型的用法中，type参数的值将简单地是直接包含overrider（可能覆盖的方法）的类或接口。例如，假设m1表示方法String.hashCode，m2表示 Object.hashCode。然后我们可以询问m1是否在类String内覆盖m2（是的）：

      assert elements.overrides(m1, m2, elements.getTypeElement("java.lang.String"));
      更有趣的情况可以通过以下示例说明，在该示例中，类A中的一个方法不覆盖接口B中同名的方法：
      class A { public void m() {} }
      interface B { void m(); }
      ...
      m1 = ...; // A.m
      m2 = ...; // B.m
      assert ! elements.overrides(m1, m2, elements.getTypeElement("A"));
      但是，当作为第三个类C的成员来看时，类A中的方法确实覆盖了B中的方法：
      class C extends A implements B {}
      ...
      assert elements.overrides(m1, m2, elements.getTypeElement("C"));
      参数：
      overrider - 第一个方法，可能是覆盖者
      overridden - 第二个方法，可能被覆盖
      type - 第一个方法所属的类或接口
      返回：
      如果第一个方法覆盖第二个方法，则返回true
      参见《Java语言规范》：
      8.4.8 继承、覆盖和隐藏
      9.4.1 继承和覆盖

    • getConstantExpression

      String getConstantExpression(Object value)
      返回表示原始值或字符串的常量表达式的文本。返回的文本以适合在源代码中表示该值的形式呈现。
      参数：
      value - 原始值或字符串
      返回：
      常量表达式的文本
      异常：
      IllegalArgumentException - 如果参数不是原始值或字符串
      参见：

    • printElements

      void printElements(Writer w, Element... elements)
      在指定的顺序将元素的表示打印到给定的写入器中。此方法的主要目的是用于诊断。输出的确切格式未指定，可能会更改。
      参数：
      w - 要打印输出的写入器
      elements - 要打印的元素

    • getName

      Name getName(CharSequence cs)
      返回与参数具有相同字符序列的名称。
      参数：
      cs - 要作为名称返回的字符序列
      返回：
      与参数具有相同字符序列的名称

    • isFunctionalInterface

      boolean isFunctionalInterface(TypeElement type)
      如果类型元素是函数式接口，则返回true，否则返回false。
      参数：
      type - 要检查的类型元素
      返回：
      如果类型元素是函数式接口，则返回true，否则返回false
      参见《Java语言规范》：
      9.8 函数式接口
      自：
      1.8

    • isAutomaticModule

      default boolean isAutomaticModule(ModuleElement module)
      如果模块元素是自动模块，则返回true，否则返回false。
      实现要求：
      此方法的默认实现返回false。
      参数：
      module - 要检查的模块元素
      返回：
      如果模块元素是自动模块，则返回true，否则返回false
      参见《Java语言规范》：
      7.7.1 依赖关系
      自：
      17

    • recordComponentFor

      default RecordComponentElement recordComponentFor(ExecutableElement accessor)
      返回给定访问器的记录组件。如果给定方法不是记录组件访问器，则返回null。
      实现要求：
      此方法的默认实现检查访问器所在元素的类型是否为RECORD，如果是，则通过调用ElementFilter.recordComponentsIn(Iterable)检索访问器所在元素的所有记录组件。如果检索到的至少一个记录组件的访问器恰好等于作为参数传递给此方法的访问器，则返回该记录组件；否则返回null。
      参数：
      accessor - 要查找记录组件的方法。
      返回：
      记录组件，如果给定方法不是记录组件访问器，则返回null
      自：
      16

    • isCanonicalConstructor

      default boolean isCanonicalConstructor(ExecutableElement e)
      如果可确定可执行元素是记录的规范构造函数，则返回true，否则返回false。请注意，在某些情况下可能没有足够的信息来确定构造函数是否是规范构造函数，例如，如果可执行元素是由类文件支持的。在这种情况下，将返回false。
      实现要求：
      此方法的默认实现无条件返回false。
      参数：
      e - 要检查的可执行元素
      返回：
      如果可确定可执行元素是记录的规范构造函数，则返回true，否则返回false
      参见《Java语言规范》：
      8.10.4.1 普通规范构造函数
      自：
      20

    • isCompactConstructor

      default boolean isCompactConstructor(ExecutableElement e)
      如果可确定可执行元素是记录的紧凑构造函数，则返回true，否则返回false。根据定义，紧凑构造函数也是一个规范构造函数。请注意，在某些情况下可能没有足够的信息来确定构造函数是否是紧凑构造函数，例如，如果可执行元素是由类文件支持的。在这种情况下，将返回false。
      实现要求:
      该方法的默认实现无条件地返回false。
      参数:
      e - 被检查的可执行元素
      返回:
      如果可确定可执行元素是记录的紧凑构造函数，则返回true，否则返回false
      参见 Java 语言规范:
      8.10.4.2 紧凑规范构造函数
      自 JDK 版本:
      20

    • getFileObjectOf

      default JavaFileObject getFileObjectOf(Element e)
      返回此元素的文件对象，如果没有这样的文件对象则返回null。

      返回的文件对象是用于构造元素的信息的参考表示。例如，在编译或注解处理期间，类Foo的源文件编译成类文件，为代表Foo的元素返回的文件对象将是源文件，而不是类文件。

      实现可以选择不支持此方法的功能，在这种情况下会抛出UnsupportedOperationException。

      在注解处理的上下文中，如果元素作为初始输入的一部分包含，或者包含文件是在注解处理工具运行期间创建的，则返回非null值。否则，可能返回null。在注解处理中，如果创建了一个类文件，那么该类文件可以作为元素的参考表示。

      如果有文件对象，包的文件对象将是一个package-info文件。即使包（隐式地）是在注解处理运行期间从该包的源文件或类文件的创建中创建的，也可能存在包而没有任何package-info文件。一个未命名包将具有null文件，因为它不能在编译单元中声明。

      如果有文件对象，模块的文件对象将是一个module-info文件。一个未命名模块将具有null文件，因为它不能在编译单元中声明。一个自动模块将具有null文件，因为它是隐式声明的。

      如果有文件对象，顶层public类或接口的文件对象将是与该类或接口对应的源文件或类文件。在这种情况下，文件的名称前导部分通常与类或接口的名称匹配。单个编译单元可以定义多个顶层类和接口，例如一个主要的public类或接口，其名称与文件名对应，以及一个或多个名称不与文件名对应的辅助类或接口。如果源文件提供了辅助类或接口的参考表示，则返回主类的文件。（辅助类或接口也可以在package-info源文件中定义，在这种情况下返回package-info文件的文件。）如果类文件提供了辅助类或接口的参考表示，则返回辅助类的单独类文件。

      对于嵌套类或接口，如果有文件对象:

      • 如果源文件提供了参考表示，则文件对象将是最外层封闭类或接口的文件对象
      • 如果类文件提供了参考表示，则文件对象将是嵌套类或接口本身的文件对象

      对于其他词法上封闭的元素，如变量、方法和构造函数，如果它们有文件对象，则文件对象将是与词法上封闭元素的封闭元素相关联的对象。

      实现要求:
      默认实现无条件地抛出UnsupportedOperationException。
      参数:
      e - 要查找文件对象的元素
      返回:
      此元素的文件对象，如果没有这样的文件对象则返回null
      抛出:
      UnsupportedOperationException - 如果不支持此功能
      自 JDK 版本:
      18