compact3

javax.annotation.processing

Interface Processor

所有已知实现类：

AbstractProcessor

public interface Processor

注释处理器的接口。

注释处理发生在一系列的rounds。在每一轮中，处理器可能会被要求process子集的注释发现源和类前一轮产生的文件。在第一轮处理输入到该工具的初始投入；这些最初的投入可以视为一个处理虚拟零轮输出。如果一个处理器被要求在一个给定的一轮处理，它将被要求处理后续的轮，包括最后一轮，即使没有任何注释，它的过程。该工具基础设施也可以要求处理器通过该工具的操作来处理生成的文件的过程。

每实现一个Processor必须要使用的工具来实例化该处理器提供一个公共的无参数构造函数。工具基础设施将与实现此接口的类进行交互如下：

1. 如果现有的Processor对象不被使用，创造一个处理器的工具调用处理器类的无参数构造函数的实例。
2. 接下来，该工具调用适当的方法ProcessingEnvironment init。
3. 后来，工具调用getSupportedAnnotationTypes，getSupportedOptions，和getSupportedSourceVersion。这些方法只被调用一次，而不是在每一轮上。
4. 适当时，工具的呼吁Processor对象的process方法；一种新的Processor对象不是每一轮了。

如果处理器对象的创建和使用没有上述协议被遵守，则处理器的行为不是由这个接口规范定义。

该工具使用发现过程找到注释处理器和决定他们是否应该运行。通过配置工具，可以控制一组潜在的处理器。例如，一个JavaCompiler候选处理器运行列表可以set directly或控制的一种service-style查找search path。其他工具的实现可能有不同的配置机制，如命令行选项；对于细节，是指特定工具的文档。该处理器的工具要求run是一种目前在root elements，什么annotation types a processor supports注释类型的功能，以及是否或不是一个处理器claims the annotation types it processes。处理器将被要求处理它所支持的注释类型的子集，它可能是一个空集合。对于一个给定的轮，该工具计算在根元素内的元素上存在的注释类型的集合。如果至少有一个注释类型存在，那么作为处理器声明注释类型，它们将从无法匹配的注释类型的集合中移除。当设置为空或没有更多的处理器是可用的，该轮已运行完成。如果没有注释，注释的处理仍然存在但只有通用处理器支持处理所有的注释类型，"*"，可以索赔（空）的注释类型。

一个注释类型被认为是存在的，如果至少有一个注释的类型存在于一个元素包围在一个圆形的根元素。为了这个目的，一个类型参数是由其generic element封闭。type uses注释，而注释的元素，被忽略时，计算是否注释类型存在。

如果它符合目前给出的定义是AnnotatedConstruct注释。总之，注释被认为是目前的目的，发现，如果它是直接存在或通过继承。一个注释不被认为是由被包装的容器注释的礼物。操作上，这相当于一个注释上存在一个元素当且仅当它是包含在Elements.getAllAnnotationMirrors(Element)呼吁该元素的结果。由于容器内的注释注释是不考虑，妥善处理repeatable annotation types，处理器应包括可重复的注释类型和其包含在一个处理器supported annotation types集注释类型。

注意，如果一个处理器支持"*"返回true，声称所有的注释。因此，一个通用的处理器被用于，例如，实施额外的有效性检查应返回false以不妨碍其他跳棋能够运行。

如果一个处理器抛出未捕获的异常，该工具可以停止其他活动注释处理器。如果一个处理器将引发错误，当前轮将运行完成，下一轮将显示一个error was raised。因为注解处理器运行在合作的环境中，处理器应该抛出未捕获的异常只有在没有错误恢复和报告是可行的情况下。

工具环境不需要支持注释处理器访问的环境资源，无论是per round或cross-round，在一个多线程的方式。

如果方法返回的配置信息的标注null处理器返回，返回其他输入无效，或抛出一个异常，该工具的基础设施必须把这当作一个错误条件。

当在不同的工具实现中运行时，注释处理器应该具有以下属性：

1. 处理一个给定的输入的结果是不是其他输入（正交）的存在或不存在的函数。
2. 处理相同的输入产生相同的输出（一致性）。
3. 处理输入一通过处理后输入B相当于处理B然后一（交换）
4. 处理一个输入不依赖于其他注释处理器（独立性）的输出的存在

的Filer接口讨论如何限制处理器可以对文件操作。

注意，这个接口的实现者可能会发现它方便地扩展AbstractProcessor而不是直接实现此接口。

从以下版本开始：

一点六

方法摘要

Modifier and Type	Method and Description
Iterable<? extends Completion>	getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText) 返回到工具基础设施建议完成注释一个。
Set<String>	getSupportedAnnotationTypes() 返回由该处理器支持的注释类型的名称。
Set<String>	getSupportedOptions() 返回由该处理器确认的选项。
SourceVersion	getSupportedSourceVersion() 返回此注释处理器支持的最新版本源版本。
void	init(ProcessingEnvironment processingEnv) 在处理环境初始化处理器。
boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) 处理来自于前一轮的类型元素的注释类型的集合，并返回是否这些注释类型所要求的这些注释类型。

方法详细信息

getSupportedOptions

Set<String> getSupportedOptions()

返回由该处理器确认的选项。加工工具的实现必须提供一种明显的特定处理器选项传递给工具本身，选择通过看 getOptions

集合中的每个字符串必须返回一段identifiers分离序列：

SupportedOptionString:

Identifiers

Identifiers:

Identifier

Identifier . Identifiers

Identifier:

Syntactic identifier, including keywords and literals

一个工具可以使用此信息来确定用户是否提供了任何一个处理器所识别的选项，在这种情况下，它可能希望报告一个警告。

。

结果

由该处理器或空集合所识别的选项，如果没有

另请参见：

SupportedOptions

getSupportedAnnotationTypes

Set<String> getSupportedAnnotationTypes()

返回由该处理器支持的注释类型的名称。结果的一个元素可能是支持的注释类型的规范（完全限定的）名称。或者可能是形成“ name.*”代表设置所有标注类型的规范名称，从“ name.”。最后， "*"本身代表着所有的注释类型的集合，包括空集。值得注意的是，处理器不应该声称 "*"除非它实际上是处理所有文件；声称不必要的注释可能会导致在某些环境中业绩增速放缓。

在集合中返回的字符串必须接受以下语法：

SupportedAnnotationTypeString:

TypeName DotStar _opt

*

DotStar:

. *

哪里类型名是定义在 The Java™ Language Specification。

结果

由该处理器支持的注释类型的名称

另请参见：

SupportedAnnotationTypes

See The Java™ Language Specification:

3.8标识符，类型名称6.5.5意义

getSupportedSourceVersion

SourceVersion getSupportedSourceVersion()

返回此注释处理器支持的最新版本源版本。

结果

由该注释处理器支持的最新版本源代码。

另请参见：

SupportedSourceVersion， ProcessingEnvironment.getSourceVersion()

init

void init(ProcessingEnvironment processingEnv)

在处理环境初始化处理器。

参数

processingEnv -设施工具框架提供了对处理器的环境

process

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

处理来自于前一轮的类型元素的注释类型的集合，并返回是否这些注释类型所要求的这些注释类型。如果 true返回，注释类型都声称和随后的处理器将不会被要求处理；如果 false返回，注释类型认领和随后的处理器可能会被要求处理。处理器可能总是返回相同的布尔值，或根据选择的标准可能会改变结果。

输入将空如果处理器支持"*"和根元素没有注释。一个Processor必须妥善处理注释空集。

参数

annotations的注释类型请求被处理

roundEnv -关于当前和前一轮的信息环境

结果

是否由该处理器声称注释类型的集合

getCompletions

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

返回到工具基础设施建议完成注释一个。自从完成被要求的，所提供的信息的注释可能是不完整的，因为如果一个源代码片段。一个处理器可能会返回一个空的迭代器。注释处理器应该集中精力和额外的有效性约束称为处理器标注的成员提供完成，例如一个 int成员的值应该介于1和10或一个字符串成员应该由一个已知的语法识别，如正则表达式或URL。

由于不完整的程序建模，有些参数可能只有部分信息或可能null。在userText element和至少一个必须non-null。如果element是non-null，annotation和member可能null。处理器可以不如果有些参数是null扔NullPointerException；如果处理器没有完井提供基于所提供的信息，一个可以返回空。处理器也可以返回一个空字符串值和消息描述为什么没有完成单完成。

完井信息可能反映了额外的注释处理器进行有效性检查。例如，考虑简单的注释：

 @MersennePrime {
    int value();
 }
 

（梅森素数的形式是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"));
 

更翔实的设置方式将包括号码每个质数：

 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是可用的，它可以检查看看只有梅森素数的一个子集S是有效的。例如，如果用户输入的值

@MersennePrime(1

userText将 "1"；和素数只有两个可能的完成：

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

有时没有有效的完成是可能的。例如，没有范围的梅森素数从9开始：

@MersennePrime(9

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

 return Collections.emptyList();
 

落成，或一个空完成有用信息

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

参数

element被注释的元素

annotation -（也许部分）注释被应用到元素

member -注释成员返回可能的完成

userText源代码的文本来完成的

结果

的注释表明完井