javax.annotation.processing

インタフェース Processor

既知のすべての実装クラス:

AbstractProcessor

public interface Processor

注釈プロセッサのインタフェース。

注釈処理は、一連のラウンド内で実行されます。各ラウンドでは、前回のラウンドで生成されたソースファイルとクラスファイルで見つかった注釈のサブセットの処理を、あるプロセッサが依頼される可能性があります。1 回目の処理ラウンドへの入力はツールの実行への初期入力になりますが、これらの初期入力は、仮想的な 0 回目の処理ラウンドの出力とみなすことができます。あるプロセッサが特定のラウンドで処理を依頼された場合、たとえそのプロセッサの処理対象となる注釈が存在しない場合でも、そのプロセッサは最終ラウンドを含む後続のラウンドでも処理を依頼されます。また、ツールインフラストラクチャーは、そのツールの操作によって暗黙的に生成されたファイルの処理を、プロセッサに依頼することもあります。

Processor の各実装では、ツールがプロセッサをインスタンス化するために使用する public 引数なしコンストラクタを提供する必要があります。ツールインフラストラクチャーとこのインタフェースを実装したクラスとの相互作用は、次のようになります。

1. 既存の Processor オブジェクトが使用されない場合、ツールは、あるプロセッサのインスタンスを作成するために、そのプロセッサのクラスの引数なしコンストラクタを呼び出す。
2. 次に、ツールは、init メソッドを適切な ProcessingEnvironment を指定して呼び出す。
3. その後、ツールは、getSupportedAnnotationTypes、getSupportedOptions、および getSupportedSourceVersion を呼び出す。これらのメソッドが呼び出されるのは、実行ごとに 1 回だけである。ラウンドごとに 1 回ではない。
4. ツールは必要に応じて、Processor オブジェクトの process メソッドを呼び出す。ラウンドごとに新しい Processor オブジェクトが作成されるわけではない。

上記のプロトコルに従わずにプロセッサオブジェクトが作成および使用された場合、そのプロセッサの動作はこのインタフェース仕様では定義されません。

ツールは、検出処理を使って注釈プロセッサを見つけ出し、それらを実行すべきかどうかを決定します。ツールを構成することで、可能性のあるプロセッサのセットを制御できます。たとえば、JavaCompiler の場合、実行候補プロセッサのリストは、直接設定 することも、サービススタイル の検索で使用される 検索パス を使って制御することもできます。ほかのツール実装は、コマンド行オプションなど、別の構成メカニズムを備えている可能性もありますが、その詳細については、特定のツールのドキュメントを参照してください。ツールがどのプロセッサに 実行 を依頼するかは、ルート要素 上にどの注釈が存在しているか、どの 注釈型を各プロセッサが処理する か、および各プロセッサが 処理対象の注釈を要求する かどうか、によって決まります。各プロセッサは、自身がサポートする注釈型のサブセットの処理を依頼されます。ただし、そのサブセットが空セットになる可能性もあります。 ある特定のラウンドで、ツールは、ルート要素上の注釈型のセットを計算します。注釈型が少なくとも 1 つ存在する場合、プロセッサが注釈型を要求するたびに、それらの注釈型が不一致の注釈セットから削除されていきます。このセットが空になるか、使用可能なプロセッサがなくなると、そのラウンドは終了します。注釈型が存在しない場合も注釈処理は実行されますが、(空の) 注釈型セットを要求できるのは、"*" の処理をサポートする汎用プロセッサだけです。

"*" をサポートするプロセッサが true を返すと、すべての注釈が要求されます。したがって、たとえば、追加の妥当性チェックの実装に使用される汎用プロセッサは、false を返すべきです。そうすれば、ほかのそのようなチェッカーの実行を妨げずにすみます。

あるプロセッサがキャッチされない例外をスローすると、ツールは、ほかのアクティブな注釈プロセッサを中止する可能性があります。あるプロセッサがエラーを発行すると、現在のラウンドは終了し、後続のラウンドが、エラーが発行された ことを通知します。注釈プロセッサは協調的な環境内で実行されるため、キャッチされない例外をプロセッサからスローするのは、エラーの復旧や報告が実行不可能な場合に限るべきです。

ツール環境は、ラウンドごとに、あるいは ラウンドをまたがって、マルチスレッド方式で環境リソースにアクセスする注釈プロセッサをサポートする必要はありません。

注釈プロセッサに関する構成情報を返すメソッドが null を返したか、その他の無効な入力を返したか、あるいは例外をスローした場合、ツールインフラストラクチャーはそれをエラー状態とみなします。

ある注釈プロセッサをさまざまなツール実装内で実行させる場合、その動作を安定させるには、そのプロセッサは次の特性を備えているべきです。

1. ある入力の処理結果がほかの入力の存在有無に依存しない (直交性)。
2. 同じ入力を処理した場合には同じ出力が得られる (一貫性)。
3. 入力 A を処理したあとに入力 B を処理することと、B のあとに A を処理することが、等価である (交換性)。
4. ある入力の処理が、ほかの注釈プロセッサからの出力の存在に依存しない (独立性)。

Filer インタフェースでは、プロセッサがどのようにファイルを操作できるかに関する制限について説明しています。

このインタフェースの実装者は、このインタフェースを直接実装するよりも、AbstractProcessor を拡張したほうが便利であると感じるはずです。

導入されたバージョン:

1.6

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
Iterable<? extends Completion>	getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText) ある注釈に対する推奨のコンプリートから成る反復可能オブジェクトを、ツールインフラストラクチャーに返します。
Set<String>	getSupportedAnnotationTypes() このプロセッサがサポートする注釈型の名前を返します。
Set<String>	getSupportedOptions() このプロセッサが認識するオプションを返します。
SourceVersion	getSupportedSourceVersion() この注釈プロセッサがサポートする最新ソースバージョンを返します。
void	init(ProcessingEnvironment processingEnv) 指定された処理環境 processingEnv を使ってプロセッサを初期化します。
boolean	process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) 前回のラウンドで生成された型要素の注釈型のセットを処理し、このプロセッサがそれらの注釈を要求するかどうかを返します。

メソッドの詳細

getSupportedOptions

Set<String> getSupportedOptions()

このプロセッサが認識するオプションを返します。処理ツールの実装は、ツール自体に渡すオプションとは別に、プロセッサ固有のオプションを渡す方法を提供しなければいけません。getOptions を参照してください。

セット内に返される各文字列は、次のような、ピリオドで区切られた一連の 識別子 になります。

SupportedOptionString:

Identifiers

Identifiers:

Identifier

Identifier . Identifiers

Identifier:

キーワードやリテラルといった、構文上の識別子

ツールは、この情報を使って、ユーザーが指定したオプションをプロセッサが認識するかどうかを判定します。認識しない場合、ツールは警告を報告します。

戻り値:

このプロセッサが認識するオプション。存在しない場合は空のコレクション

関連項目:

SupportedOptions

getSupportedAnnotationTypes

Set<String> getSupportedAnnotationTypes()

このプロセッサがサポートする注釈型の名前を返します。結果の要素は、サポートされる注釈型の正規の (完全指定) 名である可能性があります。または、「name」で始まる正規の名前を持つすべての注釈型のセットを表す「name.*」の形式である可能性があります。最後に、"*" はそれだけで、空セットを含む、すべての注釈型のセットを表します。プロセッサは、実際にすべてのファイルを処理するのでないかぎり、"*" を要求すべきではありません。不要な注釈を要求した場合、環境によってはパフォーマンスが低下する可能性があります。

セット内に返される各文字列は、次の文法に受け入れられるものでなければいけません。

SupportedAnnotationTypeString:

TypeName DotStar_opt

*

DotStar:

. *

ここで、TypeName は、「Java™ 言語仕様」で定義されているとおりです。

戻り値:

このプロセッサがサポートする注釈型の名前

関連項目:

SupportedAnnotationTypes

『Java™ 言語仕様』を参照してください。

3.8 識別子、6.5.5 型名の意味

getSupportedSourceVersion

SourceVersion getSupportedSourceVersion()

この注釈プロセッサがサポートする最新ソースバージョンを返します。

戻り値:

この注釈プロセッサがサポートする最新ソースバージョン

関連項目:

SupportedSourceVersion, ProcessingEnvironment.getSourceVersion()

init

void init(ProcessingEnvironment processingEnv)

指定された処理環境 processingEnv を使ってプロセッサを初期化します。

パラメータ:

processingEnv - ツールフレームワークがプロセッサに対して提供する機能に対する環境

process

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

前回のラウンドで生成された型要素の注釈型のセットを処理し、このプロセッサがそれらの注釈を要求するかどうかを返します。true が返された場合、それらの注釈は要求され、後続のプロセッサがそれらの処理を依頼されることはありません。false が返された場合、それらの注釈は要求されず、後続のプロセッサはおそらくそれらの処理を依頼されます。プロセッサは、常に同じ boolean 値を返すことも、選択された条件に基づいて結果を変えることもできます。

プロセッサが "*" をサポートしていてルート要素が注釈を 1 つも持たない場合、入力のセットは空になります。Processor は空の注釈セットを適切に処理しなければいけません。

パラメータ:

annotations - 処理を要求された注釈型

roundEnv - 現在および前回のラウンドについての情報に対する環境

戻り値:

このプロセッサが注釈のセットを要求するかどうか

getCompletions

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

ある注釈に対する推奨のコンプリートから成る反復可能オブジェクトを、ツールインフラストラクチャーに返します。コンプリートが要求されているため、ソースコードフラグメントの場合のように、注釈について提供される情報が不完全である可能性があります。プロセッサは、空の反復可能オブジェクトを返すことができます。注釈プロセッサは、値が 1 から 10 の範囲に収まるべき int メンバーや、正規表現や URL のような、ある既知の文法によって認識されるべき文字列メンバーなど、プロセッサに既知の追加妥当性制約を持つ注釈メンバーに対するコンプリートを提供することに、努力を集中させるべきです。

不完全なプログラムのモデル化が行われているため、いくつかのパラメータは、部分的な情報しか持たなかったり、null であったりする可能性があります。1 個以上の element および userText が null 以外の値である必要があります。element が null 以外の場合、annotation と member は null でもかまいません。プロセッサは、一部のパラメータが null でも NullPointerException をスローできません。指定された情報に基づいて提供すべきコンプリートをプロセッサが 1 つも持たない場合、空の反復可能オブジェクトを返すことができます。また、プロセッサは、空の値文字列と、コンプリートが存在しない理由を説明したメッセージとを含む単一のコンプリートを返すこともできます。

コンプリートは有益な情報であり、注釈プロセッサによって実行される追加妥当性チェックを反映する場合があります。たとえば、次のような単純な注釈があるとします。

 @MersennePrime {
    int value();
 }
 

メルセンヌ素数とは、2ⁿ - 1 の形式の素数のことを指します。この注釈型の AnnotationMirror が指定された場合、getCompletions に対するほかの引数を検査しないまま、次のように int 範囲におけるそうした素数のすべてを含むリストを返してもかまいません。

 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 が使用可能である場合には、その値をチェックすることで、メルセンヌ素数のサブセットのみが有効かどうかを判断できます。たとえば、ユーザーが次のように入力したとします。

@MersennePrime(1

userText の値は "1" になります。したがって、可能なコンプリートは次の 2 つの素数だけになります。

 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 - コンプリートの対象となるソースコードテキスト

戻り値:

注釈に対する推奨のコンプリート