Processor (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

javax.annotation.processing
接口 Processor

所有已知实现类：: AbstractProcessor

public interface Processor

注释 Processor 的接口。

注释处理是按照 round 的顺序进行的。在每次进行 round 操作时，都会请求 Processor 处理在前一个处理轮次生成的源文件和类文件上找到的注释子集。第一轮次处理的输入是工具运行的初始输入值；这些初始输入值可视为虚拟的第 0 轮次处理的输出。如果请求 Processor 在给定轮次上进行处理，那么它将被要求处理后续轮次，包括最后的轮次，即使没有要处理的注释也一样。工具框架可能还会请求 Processor 处理由工具的操作隐式生成的文件。

Processor 的每次实现都必须提供一个公共的无参数构造方法，工具将使用该构造方法实例化 Processor。工具框架将与实现此接口的类交互，如下所示：

如果不使用现有 Processor 对象，若要创建 Processor 实例，则工具将调用 Processor 类的无参数构造方法。
接下来，工具调用具有适当 ProcessingEnvironment 的 init 方法。
然后，工具调用 getSupportedAnnotationTypes、getSupportedOptions 和 getSupportedSourceVersion。这些方法只在每次运行时调用一次，并非对每个处理轮次调用。
在适当的时候，工具在 Processor 对象上调用 process 方法；无需为每个处理轮次创建新的 Processor 对象。

如果创建了一个 Processor 对象，并在没有遵循上述协议的情况下使用它，那么该 Processor 的行为将不是由此接口规范所定义的。

该工具使用一个搜索过程 来查找注释 Processor，并确定是否应该运行它们。通过配置该工具，可以控制潜在的 Processor 集合。例如，对于 JavaCompiler，要运行的候选 Processor 列表可以是直接设置的，也可以是通过用于服务样式查找的搜索路径所控制的 Processor 列表。其他工具实现可能有不同的配置机制，比如命令行选项；有关详细信息，请参考特定工具的文档。工具请求运行哪一个 Processor 取决于根元素上出现哪些注释、Processor 处理哪些注释类型以及 Processor 是否声明它所处理的注释。Processor 将被要求处理它所支持的注释类型的子集，该集合可能是一个空集。对于给定的 round，工具计算根元素上的注释类型集。如果至少存在一个注释类型，那么当 Processor 声明注释类型时，将从不匹配的注释集移除它们。当该集合为空或者没有更多 Processor 可用时，round 将运行完成。如果不存在注释类型，注释处理仍然会发生，但只有支持处理 "*" 的通用 Processor 可以声明（空）注释类型集。

注意，如果 Processor 支持 "*" 并返回 true，则声明所有注释。因此，通用 Processor（例如，用来实现其他有效性检查的通用 Processor）应该返回 false，以便允许运行其他这类检查器。

如果 Processor 抛出一个未捕获的异常，那么工具可能停止其他活动的注释 Processor。如果某一 Processor 产生错误，那么当前 round 将运行完成，并且后续 round 将指示产生了错误。因为注释 Processor 是在协作环境下运行的，所以 Processor 只在错误恢复和报告都不可行的情况下才会抛出一个未捕获的异常。

不要求工具环境支持以多线程方式访问环境资源（每个 round 或跨 round）的注释 Processor。

如果返回有关注释 Processor 配置信息的方法返回 null、返回其他无效输入，或者抛出一个异常，则工具框架必须将此视为一种错误状态。

为了可靠起见，当在不同工具实现中运行时，注释 Processor 应该具有以下属性：

处理某一给定输入的结果不是其他输入存在或不存在的函数（正交性）。
处理相同的输入将产生相同的输出（一致性）。
处理输入 A 之后处理输入 B 等同于处理 B 然后处理 A（互换性）。
处理输入并不依赖于其他注释 Processor 输出的存在（独立性）。

Filer 接口讨论了关于 Processor 如何在文件上进行操作的限制。

注意，此接口的实现者可能会发现扩展 AbstractProcessor 比直接实现此接口更便捷。

从以下版本开始：: 1.6

方法摘要

Iterable<? extends Completion> getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText)
          向工具框架返回某一注释的建议 completion 迭代。

Set<String> getSupportedAnnotationTypes()
          返回此 Processor 支持的注释类型的名称。

Set<String> getSupportedOptions()
          返回此 Processor 识别的选项。

SourceVersion getSupportedSourceVersion()
          返回此注释 Processor 支持的最新的源版本。

void init(ProcessingEnvironment processingEnv)
          用处理环境初始化 Processor。

boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)
          处理先前 round 产生的类型元素上的注释类型集，并返回这些注释是否由此 Processor 声明。

方法摘要
`Iterable<? extends Completion>`	`getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText)` 向工具框架返回某一注释的建议 completion 迭代。
`Set<String>`	`getSupportedAnnotationTypes()` 返回此 Processor 支持的注释类型的名称。
`Set<String>`	`getSupportedOptions()` 返回此 Processor 识别的选项。
`SourceVersion`	`getSupportedSourceVersion()` 返回此注释 Processor 支持的最新的源版本。
`void`	`init(ProcessingEnvironment processingEnv)` 用处理环境初始化 Processor。
`boolean`	`process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv)` 处理先前 round 产生的类型元素上的注释类型集，并返回这些注释是否由此 Processor 声明。

方法详细信息

getSupportedOptions

Set<String> getSupportedOptions()

返回此 Processor 识别的选项。处理工具的实现必须提供一种方式来传递特定于 Processor 的选项，这些选项不同于传递给工具自身的选项，请参见 getOptions。

集合中返回的每个字符串都必须是句点分隔的标识符序列：

SupportedOptionString：
标识符

标识符：
标识符
标识符 .标识符

标识符：
语法标识符，包括关键字和字面值

工具可以使用此信息来确定用户提供的任意选项是否无法被任何 Processor 识别，在这种情况下，可能希望它报告警报。

返回：: 此 Processor 识别的选项；如果没有这样的选项，则返回一个空集合
另请参见：: SupportedOptions

getSupportedAnnotationTypes

Set<String> getSupportedAnnotationTypes()

返回此 Processor 支持的注释类型的名称。结果元素可能是某一受支持注释类型的规范（完全限定）名称。它也可能是 "name.*" 形式的名称，表示所有以 "name." 开头的规范名称的注释类型集合。最后，"*" 自身表示所有注释类型的集合，包括空集。注意，Processor 不应声明 "*"，除非它实际处理了所有文件；声明不必要的注释可能导致在某些环境中的性能下降。

集合中返回的每个字符串必须符合以下语法：

SupportedAnnotationTypeString:
TypeName DotStar_opt
*

DotStar:
. *

其中 TypeName 在 Java 语言规范 中定义。

返回：: 此 Processor 所支持的注释类型的名称
另请参见：: SupportedAnnotationTypes

getSupportedSourceVersion

SourceVersion getSupportedSourceVersion()

返回此注释 Processor 支持的最新的源版本。

返回：: 此注释 Processor 所支持的最新的源版本。
另请参见：: SupportedSourceVersion, ProcessingEnvironment.getSourceVersion()

init

void init(ProcessingEnvironment processingEnv)

用处理环境初始化 Processor。

参数：: processingEnv - 工具框架提供给 Processor 的设施的环境

process

boolean process(Set<? extends TypeElement> annotations,
                RoundEnvironment roundEnv)

处理先前 round 产生的类型元素上的注释类型集，并返回这些注释是否由此 Processor 声明。如果返回 true，则这些注释已声明并且不要求后续 Processor 处理它们；如果返回 false，则这些注释未声明并且可能要求后续 Processor 处理它们。Processor 可能总是返回相同的 boolean 值，或者可能基于所选择的标准而返回不同的结果。

如果 Processor 支持 "*" 并且根元素没有注释，则输入集合将为空。Processor 必须妥善处理空注释集。

参数：: annotations - 请求处理的注释类型; roundEnv - 有关当前和以前 round 的信息的环境
返回：: 注释集是否由此 Processor 声明

getCompletions

Iterable<? extends Completion> getCompletions(Element element,
                                              AnnotationMirror annotation,
                                              ExecutableElement member,
                                              String userText)

向工具框架返回某一注释的建议 completion 迭代。因为要求 completion，所以提供的有关注释的信息可能是不完整的，就像用于源代码片段的信息一样。Processor 可能返回一个空迭代。注释 Processor 应该将其工作集中在提供注释成员的 completion 上，这些成员具有 Processor 已知的其他有效性约束，例如值应该在 1 和 10 之间的 int 成员，或者应该由已知语法识别的字符串成员，比如正则表达式或者 URL。

因为将为不完整的程序建立模型，所以某些参数可能只有部分信息，或者可能为 null。element 和 userText 中必须至少有一个不为 null。如果 element 不为 null，则 annotation 和 member 可以为 null。如果某些参数为 null，Processor 可能不会抛出 NullPointerException；如果 Processor 基于所提供的信息不提供 completion，则可能返回一个空迭代。Processor 也可能返回一个具有空值字符串的单个 completion，以及描述不提供 completion 的原因的消息。

completion 包含许多信息，它可以反映注释 Processor 执行的其他有效性检查。例如，考虑以下简单注释：

@MersennePrime {
int value();
 }

（素数 Mersenne 是 2ⁿ - 1 形式的素数。)如果给定此注释类型的 AnnotationMirror，则可以返回 int 范围内所有这类素数的列表，而无需检查 getCompletions 的其他任何参数：

import static javax.annotation.processing.Completions.*;
 ...
return Arrays.asList(of("3"),
of("7"),
of("31"),
of("127"),
of("8191"),
of("131071"),
of("524287"),
of("2147483647"));

包含更多信息的 completion 集合还包括每个素数的数量：

return Arrays.asList(of("3",          "M2"),
of("7",          "M3"),
of("31",         "M5"),
of("127",        "M7"),
of("8191",       "M13"),
of("131071",     "M17"),
of("524287",     "M19"),
of("2147483647", "M31"));

不过，如果 userText 是可用的，则可以检查它，以查看是否只有素数 Mersenne 的子集是有效的。例如，如果用户键入了以下内容

@MersennePrime(1

则 userText 的值将是 "1"；并且只有两个素数可能是 completion：

return Arrays.asList(of("127",        "M7"),
of("131071",     "M17"));

有时可能不是有效的 completion。例如，范围内没有以 9 开头的 Mersenne 素数：

@MersennePrime(9

在这种情况下，适当的响应是返回一个空的 completion 列表，

return Collections.emptyList();

或者返回一个包含帮助消息的单个空 completion

return Arrays.asList(of("", "No in-range Mersenne primes start with 9"));

参数：: element - 将被注释的元素; annotation - 将应用于元素的注释（可能是一部分）; member - 为其返回可能 completion 的注释成员; userText - 将补充完整的源代码文本
返回：: 注释的建议 completion

概述