注釈処理ツール (apt) 入門

次の項目について説明します。

• apt ツールは非推奨になりました
• apt とは
• なぜ apt を使用するべきか
• apt の使用方法
• apt ツールの動作
• 宣言と型
• FAQ
• 関連項目

apt ツールは非推奨になりました

パッケージ apt に含まれる apt ツールおよびその関連 API は、JDK 7 以降で推奨されなくなり、JDK の次回メジャーリリースで削除される予定となっています。javac ツールで利用可能なオプションと、パッケージ javax.annotation.processing および javax.lang.model に含まれる API を使用して、注釈を処理してください。

apt API の代替のサマリー

次の表では、apt API の代替について概要を示します。

apt とは

なぜ apt を使用するべきか

注釈に基づいて派生ファイルを生成する場合、ドックレットと比較すると apt には次の利点があります

• 整理された宣言のモデルとプログラムの現在の型の構造を持つ
• 最新の API 設計を使用して、配列の代わりにジェネリックコレクションを返したり、宣言と型を操作するためのビジターを提供したりする
• 新しく生成されたファイルの再帰的な処理をサポートし、元となるソースファイルと生成されたソースファイルのコンパイルを自動的に実行できる

apt の使用方法

概要

注釈プロセッサの開発

• com.sun.mirror.apt: ツールと対話するインタフェース
• com.sun.mirror.declaration: フィールド、メソッド、クラスなどのソースコード宣言をモデル化するインタフェース
• com.sun.mirror.type: ソースコードに検出された型をモデル化するインタフェース
• com.sun.mirror.util: ビジターを含む、型と宣言を処理するためのさまざまなユーティリティー

プロセッサのインスタンスが、対応するファクトリ AnnotationProcessorFactory により返されます。apt ツールはファクトリの getProcessorFor メソッドを呼び出しプロセッサを保持します。この呼び出しの間に、ツールは AnnotationProcessorEnvironment を提供します。この環境でプロセッサは、開始するために必要なあらゆるもの (操作しているプログラム構造への参照や、新しいファイルを作成して警告とエラーメッセージを渡すことにより apt ツールと通信および連携する方法など) を検出します。

ファクトリを見つけるには 2 つの方法があります。使用するファクトリは「-factory」コマンド行オプションを使用して指定できます。または apt discovery プロシージャー中にファクトリを見つけることもできます。「-factory」オプションを使用すると、既知の単一ファクトリをもっとも簡単に実行できます。このオプションは実行される方法をファクトリがより詳細に制御する必要がある場合にも使用されます。特定のパスでファクトリを検出するために、検出プロシージャーは次に示す方法で jar ファイルから META-INF/services 情報を取得します。

「-factory」オプションを使用して注釈プロセッサを作成して使用するには:

1. 対象の注釈型の AnnotationProcessor を作成できる、AnnotationProcessorFactory を記述します。
2. クラスパスに tools.jar を指定した状態で javac を使用してプロセッサおよびファクトリをコンパイルします。tools.jar には com.sun.mirror.* インタフェースが含まれます。
3. コンパイルされたクラスファイル、またはコクラスファイルを含む jar ファイルを、apt を呼び出すときの適切なパスに置きます。

3. META-INF/services に、com.sun.mirror.apt.AnnotationProcessorFactory という名前の UTF-8 エンコードテキストファイル (内容は具象ファクトリクラスの完全修飾名のリスト、1 行に 1 個) を作成します。 (sun.misc.Service により使用されるものと同じ形式です)。
4. ファクトリ、プロセッサ、および META-INF/services 情報を jar ファイルにパッケージ化します。
5. jar ファイルを apt を呼び出すときの適切な場所に置きます。適切なパスについては、「検出」セクションで説明します。

注釈プロセッサの簡単な例

import com.sun.mirror.apt.*;
import com.sun.mirror.declaration.*;
import com.sun.mirror.type.*;
import com.sun.mirror.util.*;

import java.util.Collection;
import java.util.Set;
import java.util.Arrays;

import static java.util.Collections.*;
import static com.sun.mirror.util.DeclarationVisitors.*;

/*
 * This class is used to run an annotation processor that lists class
 * names.  The functionality of the processor is analogous to the
 * ListClass doclet in the Doclet Overview.
 */
public class ListClassApf implements AnnotationProcessorFactory {
    // Process any set of annotations
    private static final Collection<String> supportedAnnotations
        = unmodifiableCollection(Arrays.asList("*"));

    // No supported options
    private static final Collection<String> supportedOptions = emptySet();

    public Collection<String> supportedAnnotationTypes() {
        return supportedAnnotations;
    }

    public Collection<String> supportedOptions() {
        return supportedOptions;
    }

    public AnnotationProcessor getProcessorFor(
            Set<AnnotationTypeDeclaration> atds,
            AnnotationProcessorEnvironment env) {
        return new ListClassAp(env);
    }

    private static class ListClassAp implements AnnotationProcessor {
        private final AnnotationProcessorEnvironment env;
        ListClassAp(AnnotationProcessorEnvironment env) {
            this.env = env;
        }

        public void process() {
            for (TypeDeclaration typeDecl : env.getSpecifiedTypeDeclarations())
                typeDecl.accept(getDeclarationScanner(new ListClassVisitor(),
                                                      NO_OP));
        }

        private static class ListClassVisitor extends SimpleDeclarationVisitor {
            public void visitClassDeclaration(ClassDeclaration d) {
                System.out.println(d.getQualifiedName());
            }
        }
    }
}

このプロセッサの例では、いくつかの新しい言語とライブラリ機能が使用されています。まず、さまざまなユーティリティーメソッドの簡易名を使用できるように、static import が使用されます。たとえば、
「unmodifiableCollection」を
「Collections.unmodifiableCollection」
の代わりに使用できます。
次に、ジェネリックコレクションが全体で使用されています。Arrays.asList メソッドが可変長引数メソッドになったので、コンマ区切りの文字列リストを受け取って目的の要素のリストを作成できます。Collections.emptySet メソッドはジェネリックメソッドで、型保証された空のセットを作成するために使用できます。process メソッド内の for ループは、コレクションをイテレートする拡張 for ループです。

注釈をプロセスに指定する

*

すべての注釈を処理する。これは空の注釈リストも処理する。つまり、* を処理するファクトリは、重要なプロセッサを提供することを要求される可能性がある (注釈が存在しない場合でも)。この機能により com.sun.mirror API を使用して、一般的なソースコード処理ツールを記述できる。

foo.bar.Baz

正規名が「foo.bar.Baz」である注釈を処理する。

foo.bar.*

正規名が「foo.bar.」で始まる注釈を処理する。

apt ツールは、処理するファクトリの注釈セットをファクトリに提示します。注釈セットと注釈プロセッサ環境に基づいて、ファクトリは単一注釈プロセッサを返します。ファクトリが複数の注釈プロセッサを返したい場合はどうなりますか。ファクトリは com.sun.mirror.apt.AnnotationProcessors.getCompositeAnnotationProcessor を使用して、複数の注釈プロセッサを組み合わせてオペレーションを順番に行うことができます。

認識するコマンド行オプションを指定する

apt コマンド行

apt 固有のオプションを次に示します。

-s dir

プロセッサ生成ソースファイルが配置されるディレクトリルートを指定します。ファイルはパッケージ名前空間に基づいてサブディレクトリに配置されます

-nocompile

ソースファイルをクラスファイルにコンパイルしません。

-print

指定したタイプのテキスト表現を出力します。注釈処理またはコンパイルは行いません。

-A[key[=val]]

注釈プロセッサへ渡すオプションです。このオプションは、apt が直接解釈するのではなく、それぞれのプロセッサで使用できるようになります。

-factorypath path

注釈プロセッサファクトリを検索する場所を指定します。このオプションを使用する場合、クラスパスのファクトリは検索されません。

-factory classname

使用する AnnotationProcessorFactory の名前。デフォルト検出プロセスをバイパスします。

-d dir

プロセッサと javac 生成のクラスファイルを置く場所を指定します。

-cp path または -classpath path

ユーザークラスファイルと注釈プロセッサファクトリを検索する場所を指定します。-factorypath が指定されている場合、クラスパスのファクトリは検索されません。

-XListAnnotationTypes

検出された注釈型をリストします

-XListDeclarations

指定およびインクルードされた宣言をリストします

-XPrintAptRounds

初期および再帰的 apt ラウンドに関する情報を出力する

-XPrintFactoryInfo

ファクトリが処理を要求されている注釈に関する情報を出力します

apt ツールの動作

検出

ファクトリクラスが注釈処理の複数のラウンドで使用される場合、ファクトリクラスは 1 回ロードされ、ファクトリの getProcessorFor メソッドがラウンドごとに 1 回呼び出されます。これによりファクトリは、ラウンドをまたがって静的状態を保存できます。

-factory オプションが使用されている場合、指定されたファクトリだけが照会されます。

apt 処理のラウンド

リスナー

リターンコード

宣言と型

ミラー API は、主に com.sun.mirror.declaration パッケージ内の Declaration インタフェースおよびそのサブインタフェースの階層によってソースコード構造体を表します。Declaration は、パッケージ、クラス、メソッドなどのプログラム要素を表し、通常はソースコードの特定部分に 1 対 1 で対応しています。Declarations は注釈可能な構造です。

型は、com.sun.mirror.type パッケージ内の TypeMirror インタフェースおよびそのサブインタフェースの階層により表現されます。型にはプリミティブ型、クラスおよびインタフェース型、配列型、型変数、およびワイルドカード型が含まれます。

API は宣言と型を慎重に区別します。これは、1 つの宣言が型ファミリ全体を定義できる、ジェネリック型においてもっとも重要です。たとえば、java.util.Set クラスの宣言は次に対応します。

• パラメータ化された型 java.util.Set<String>
• パラメータ化された型 java.util.Set<Number>
• パラメータ化された型 java.util.Set<T> (String または Number 以外の何らかの型 T 用)
• raw 型 java.util.Set。

TypeMirror は、ソースコード内の戻り値型、パラメータ型などをモデル化するために使用されます。参照型用の TypeMirror は、型から対応する宣言へのマッピング (たとえば、java.util.Set<String> 用のミラー型から java.util.Set 用の宣言へ) を提供します。

FAQ

• 「Debian Advanced Packaging Tool」について知っていますか。
  はい。
• 注釈プロセッサはドックレットと比べてどうですか。
  2 つのエンティティーにはたしかにいくつかの類似点があります。たとえば、両方ともビルド時にリフレクション API を使用してソースコードを処理します。ただし、注釈プロセッサで使用されたミラー API は、Java プログラミング言語の現在の型システムをより良くモデル化します。またデフォルトでは、実行される注釈プロセッサは、-doclet オプションと類似したメカニズムだけではなく、ソースコードに存在する注釈によって決定されます。つまり、単一の不変のドックレットを実行する代わりに、apt は潜在的に実行される複数のプロセッサを動的に選択します。
• ローカル変数の注釈はどのように処理できますか。
  ローカル変数の注釈は、宣言階層がメソッドまたはコンストラクタ内のプログラム構造をモデル化しないので、表示されません。
• com.sun.mirror.apt 内にファクトリとプロセッサのインタフェースが個別に存在するのはなぜですか。
  処理方法の決定と処理タイミングの制御を組み合わせることはできます。しかし、この 2 つのステップを区別して、ファクトリとプロセッサのインタフェースに分離することを選択しました。
• ミラーとは何ですか。
  リフレクションを見つける場所です。リフレクションプログラミングでは、ミラー設計によって、表現されているオブジェクトと表現を実行しているオブジェクトを常に分離して管理しています。
• ファクトリがサポートする注釈とおよびファクトリがサポートするオプションが、ファクトリクラスの注釈としてエンコードされる代わりに、メソッドにより返されていたのはなぜですか。
  インタフェースを実装することは、必要な機能をクラスが持っていることを示す (どの注釈を処理するかを示す) ための普通のメカニズムです。特定の注釈型で注釈されることをクラスに要求する言語メカニズムはありません。したがって、技術的には注釈でそのような情報をエンコードすることはできますが、そうすることはインタフェース内でメソッドを持つことの型安全性を欠くことになります。
• ビジターに慣れていません。使用する必要がありますか。
  ビジターパターンは「Gang of Four」の『Design Patterns』という本の中で紹介されている標準パターンの 1 つです。このパターンは、型を明示的にテストせずに型依存オペレーションを呼び出す、強力なメカニズムを提供します。ただし、ビジターの使用は必須ではありません。

関連項目

• apt Tool Reference Page
• ミラー API の仕様