javax.annotation.processing
介面 Processor

所有已知實作類別：

AbstractProcessor

public interface Processor

註釋 Processor 的介面。

註釋處理是按照 round 的順序進行的。在每次進行 round 操作時，都會請求 Processor 處理在前一個處理輪次產生的源檔案和類別檔案上找到的註釋子集。第一輪次處理的輸入是工具運行的初始輸入值；這些初始輸入值可視為虛擬的第 0 輪次處理的輸出。如果請求 Processor 在給定輪次上進行處理，那麼它將被要求處理後續輪次，包括最後的輪次，即使沒有要處理的註釋也一樣。工具框架可能還會請求 Processor 處理由工具的操作隱式產生的檔案。

Processor 的每次實作都必須提供一個公共的無參數建構子，工具將使用該建構子實例化 Processor。工具框架將與實作此介面的類別交互，如下所示：

1. 如果不使用現有 Processor 物件，若要創建 Processor 實例，則工具將調用 Processor 類別的無參數建構子。
2. 接下來，工具調用具有適當 ProcessingEnvironment 的 init 方法。
3. 然後，工具調用 getSupportedAnnotationTypes、getSupportedOptions 和 getSupportedSourceVersion。這些方法只在每次運行時調用一次，並非對每個處理輪次調用。
4. 在適當的時候，工具在 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 應該具有以下屬性：

1. 處理某一給定輸入的結果不是其他輸入存在或不存在的函數（正交性）。
2. 處理相同的輸入將產生相同的輸出（一致性）。
3. 處理輸入 A 之後處理輸入 B 等同於處理 B 然後處理 A（互換性）。
4. 處理輸入並不依賴於其他註釋 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 宣告。

方法詳細資訊

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