モジュール java.compiler
パッケージ javax.annotation.processing

インタフェースFiler

  • public interface Filer
    このインタフェースは、注釈プロセッサによる新しいファイルの作成をサポートしています。 このやり方で作成されたファイルは、このインタフェースを実装している注釈処理ツールに認識され、さらにそのツールで管理されることもできます。 そのようにして作成されたソース・ファイルとクラス・ファイルは、それらの内容の書込みに使用されたWriterまたは OutputStream上でcloseメソッドが呼び出されると、それ以降の処理ラウンドではこのツールによって処理対象とみなされます。 区別されるファイルは3種類あります。ソース・ファイル、クラス・ファイル、および補助リソース・ファイルです。

    新しく作成されたファイルは、2つのサポートされた位置(論理ファイル・システム内のサブツリー)に配置されます。それぞれ、新しいソース・ファイル、新しいクラス・ファイルに使用されます。 これらの位置は、-sや-dなどのフラグを使ってツールのコマンド行で指定されます。 実際の新しいソース・ファイルの場所と新しいクラス・ファイルの場所は、ツールの特定の実行で区別される場合もあれば、されない場合もあります。 リソース・ファイルはどちらかの位置で作成できます。 リソースの読書きを行うメソッドは、相対名の引数を取ります。 相対名は、一連のパス・セグメント(null以外、空以外)を「'/'」で区切った形式の名前です。「'.'」または「'..'」は無効なパス・セグメントです。 有効な相対名は、RFC 3986セクション3.3の「path-rootless」ルールに適合する必要があります。

    ファイル作成メソッドは可変個数の引数を取りますが、これは、依存関係の管理レベルを向上させるためのヒントとして、作成元要素をツール・インフラストラクチャに提供できるようにするためです。 元の要素は、注釈プロセッサが新しいファイルを作成しようとしたタイプまたはパッケージ( package-infoファイルを表す)またはモジュール( module-infoファイルを表す)です。 たとえば、ある注釈プロセッサが、次のコードの処理結果として、ソース・ファイル GeneratedFromUserSourceを作成しようとしている場合、 

      @Generate
  public class UserSource {}
    次のように、作成メソッド呼出しの一部としてUserSourceの型要素が渡されるべきです。 
          filer.createSourceFile("GeneratedFromUserSource",
                             eltUtils.getTypeElement("UserSource"));
    作成元要素が存在しない場合は、何も渡す必要がありません。 この情報は、インクリメンタル環境で、プロセッサの再実行や生成されたファイルの削除の必要性を判断するために使用される可能性があります。 非インクリメンタル環境では、作成元要素の情報は無視されます。

    注釈処理ツールを実行するたびに、指定されたパス名を持つファイルが1回だけ作成されます。 このファイルをはじめて作成するときにファイルがすでに存在している場合、ファイルの古い内容は削除されます。 それ以降、その実行の間に同じファイルの作成が試みられるたびに、FilerExceptionがスローされます。同じ型名またはパッケージ名に対してクラス・ファイルとソース・ファイルの両方の作成が試みられた場合も同様です。 ツールへの初期入力は、0回目のラウンドで作成されたものであるとみなされます。したがって、これらの入力のいずれかに対応するソース・ファイルやクラス・ファイルの作成が試みられると、FilerExceptionがスローされます。

    一般に、プロセッサは、何らかのプロセッサによって生成されたものではない既存ファイルを、故意に上書きしようとしてはいけません。 Filerは、java.lang.Objectのような既存の型に対応するファイルを開く試みを、拒否する可能性があります。 同様に、注釈処理ツールの呼出し元は、生成されたものではない既存ファイルの上書きを検出されたプロセッサが試みるように、ツールを故意に構成してはいけません。

    プロセッサは、その型にアクセスできるように環境が構成されている場合、javax.annotation.Generatedアノテーションを含めることで、ソース・ファイルまたはクラス・ファイルが生成されることを示すことができます。

    APIに関するノート:
    decorator形式のパターンを使用すると、ファイルを上書きする効果がいくつか得られます。 あるクラスを直接変更する代わりに、そのクラスを適切に設計することで、注釈処理によってそのスーパー・クラスまたはサブクラスが生成されるようにします。 サブクラスが生成される場合、その親クラスは、publicコンストラクタではなくファクトリを使用するように設計できます。そうすれば、サブクラスのインスタンスのみが、親クラスのクライアントに対して提供されます。
    導入されたバージョン:
    1.6

    • メソッドの詳細

      • createSourceFile

        JavaFileObject createSourceFile​(CharSequence name,
                                Element... originatingElements)
                         throws IOException
        新しいソース・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。 タイプのソース・ファイル、またはパッケージを作成できます。 ファイルの名前とパス(root output location for source filesに対する相対パス)は、そのファイルで宣言される項目の名前と、項目に指定されたモジュール(存在する場合)に基づいています。 1つのファイル内で複数の型が宣言されている場合(つまり、1つのコンパイル単位)、ファイルの名前は主体の最上位型の名前(たとえば、公開型)に対応している必要があります。

        ソース・ファイルは、パッケージ注釈など、パッケージに関する情報の格納用として作成することもできます。 名前付きパッケージのソース・ファイルを作成するには、name引数にパッケージ名の後に".package-info"を続けます。名前なしパッケージのソース・ファイルを作成するには、"package-info"を使用します。

        オプションのモジュール名は、タイプ名またはパッケージ名の先頭に付加され、/文字で区切られます。 たとえば、a.B型のソース・ファイルをモジュールfooに作成するには、"foo/a.B"のname引数を使用します。

        明示的なモジュール接頭辞が指定されておらず、モジュールが環境でサポートされている場合、適切なモジュールが推測されます。 適切なモジュールを推測できない場合は、FilerExceptionがスローされます。 実装では、推論の一部として注釈処理ツールの構成に関する情報を使用できます。

        名前付きモジュール内の名前なしパッケージに対するソース・ファイルの作成はサポートされていません。

        APIに関するノート:
        特定の文字セットを使用してファイルの内容をエンコードするには、戻されたオブジェクトのOutputStreamから、選択した文字セットを持つOutputStreamWriterを作成できます。 返されたオブジェクトのWriterを直接使用して書込みが行われる場合、その文字セットは実装によって決定されます。 注釈処理ツールには、これを指定するための-encodingフラグやそれに類するものが用意されている可能性があります。それ以外の場合、それは通常、プラットフォームのデフォルト・エンコーディングになります。

        後続処理でのエラー発生を防ぐために、この実行で使用されているソース・バージョンに、ソース・ファイルの内容を準拠させるようにしてください。

        実装上のノート:
        リファレンス実装では、注釈処理ツールが単一のモジュールMを処理している場合、明示的なモジュール接頭辞なしで作成されたファイルのモジュールとしてMが使用されます。 ツールが複数のモジュールを処理していて、Elements.getPackageElement(package-of(name))がパッケージを返した場合、返されたパッケージを所有するモジュールがターゲット・モジュールとして使用されます。 前述のルールを使用してターゲット・モジュールを決定できない場合は、別のオプションを使用してターゲット・モジュールを提供できます。
        パラメータ:
        name - このファイル内で宣言される主体の型の正規の(完全指定)名。パッケージ情報ファイルの場合は、パッケージ名+".package-info"
        originatingElements - このファイルの作成に因果関係がある型、パッケージまたはモジュール要素、あるいはnull
        戻り値:
        新しいソース・ファイルに書き込むためのJavaFileObject
        例外:
        FilerException - 同じパス名がすでに作成されている場合、同じタイプがすでに作成されている場合、作成がリクエストされたエンティティに対して名前が無効な場合、ターゲット・モジュールを決定できない場合、ターゲット・モジュールが書込み可能でない場合、または環境がモジュールをサポートしていないときにモジュールが指定されている場合。
        IOException - ファイルを作成できない場合
        The Java™Language Specificationを参照してください。
        7.3 コンパイル・ユニット

      • createClassFile

        JavaFileObject createClassFile​(CharSequence name,
                               Element... originatingElements)
                        throws IOException
        新しいクラス・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。 型のクラス・ファイル、またはパッケージを作成できます。 ファイルの名前とパス(クラス・ファイルのルート出力場所に相対的)は、宣言するアイテムの名前と、アイテムに指定されたモジュール(存在する場合)に基づきます。

        クラス・ファイルは、パッケージ注釈など、パッケージに関する情報の格納用として作成することもできます。 名前付きパッケージのクラス・ファイルを作成するには、name引数にパッケージ名の後に".package-info"を続けます。名前なしパッケージのクラス・ファイルの作成はサポートされていません。

        オプションのモジュール名は、タイプ名またはパッケージ名の先頭に付加され、/文字で区切られます。 たとえば、a.B型のクラス・ファイルをモジュールfooに作成するには、"foo/a.B"のname引数を使用します。

        明示的なモジュール接頭辞が指定されておらず、モジュールが環境でサポートされている場合、適切なモジュールが推測されます。 適切なモジュールを推測できない場合は、FilerExceptionがスローされます。 実装では、推論の一部として注釈処理ツールの構成に関する情報を使用できます。

        名前付きモジュール内の名前のないパッケージに対するクラス・ファイルの作成はサポートされていません。

        APIに関するノート:
        後続処理でのエラー発生を防ぐために、この実行で使用されているソース・バージョンに、クラス・ファイルの内容を準拠させるようにしてください。
        実装上のノート:
        リファレンス実装では、注釈処理ツールが単一のモジュールMを処理している場合、明示的なモジュール接頭辞なしで作成されたファイルのモジュールとしてMが使用されます。 ツールが複数のモジュールを処理していて、Elements.getPackageElement(package-of(name))がパッケージを返した場合、返されたパッケージを所有するモジュールがターゲット・モジュールとして使用されます。 前述のルールを使用してターゲット・モジュールを決定できない場合は、別のオプションを使用してターゲット・モジュールを提供できます。
        パラメータ:
        name - 書き込む型のバイナリ名。パッケージ情報ファイルの場合は、パッケージ名+".package-info"
        originatingElements - このファイルの作成に因果関係がある型、パッケージまたはモジュール要素、あるいはnull
        戻り値:
        新しいクラス・ファイルに書き込むためのJavaFileObject
        例外:
        FilerException - 同じパス名がすでに作成されている場合、同じタイプがすでに作成されている場合、その名前はタイプに対して有効ではありません。ターゲット・モジュールが判別できない場合、ターゲット・モジュールが書込み可能でない場合、または環境がモジュールをサポートしていない場合にモジュールが指定されている場合。
        IOException - ファイルを作成できない場合

      • createResource

        FileObject createResource​(JavaFileManager.Location location,
                          CharSequence moduleAndPkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                   throws IOException
        書込み対象の新しい補助リソース・ファイルを作成し、それに対応するファイル・オブジェクトを返します。 このファイルは、新しく作成されたソース・ファイルやバイナリ・ファイルと一緒に格納することも、サポートされているほかの場所に格納することもできます。 場所CLASS_OUTPUTとSOURCE_OUTPUTがサポートされている必要があります。 リソースには、一部のモジュールまたはパッケージ(ソース・ファイルやクラス・ファイルなど)を基準として、相対パス名で名前を付けることができます。 緩い意味では、新しいファイルのフルパス名は、location、moduleAndPkgおよびrelativeNameを連結したものになります。 moduleAndPkgに/文字が含まれている場合、/文字の前の接頭辞はモジュール名で、/文字の後の接尾辞はパッケージ名です。 パッケージの接尾辞は空である可能性があります。 moduleAndPkgに/文字が含まれていない場合、引数全体がパッケージ名として解釈されます。

        指定された場所がモジュール指向の場所でも複数のモジュールを含む出力場所でもなく、明示的なモジュール接頭辞が指定されている場合は、FilerExceptionがスローされます。

        指定された場所がモジュール指向の場所か、または複数のモジュールを含む出力場所であり、明示的なモジュール接頭辞が指定されていない場合、適切なモジュールが推測されます。 適切なモジュールを推測できない場合は、FilerExceptionがスローされます。 実装では、推論の一部として注釈処理ツールの構成に関する情報を使用できます。

        このメソッドで作成されたファイルは、ファイルのフルパス名が新しいソースファイルまたは新しいクラスファイルのフルパス名に対応していても、注釈処理に登録されません。

        実装上のノート:
        リファレンス実装では、注釈処理ツールが単一のモジュールMを処理している場合、明示的なモジュール接頭辞なしで作成されたファイルのモジュールとしてMが使用されます。 ツールが複数のモジュールを処理していて、Elements.getPackageElement(package-of(name))がパッケージを返した場合、返されたパッケージを所有するモジュールがターゲット・モジュールとして使用されます。 前述のルールを使用してターゲット・モジュールを決定できない場合は、別のオプションを使用してターゲット・モジュールを提供できます。
        パラメータ:
        location - 新しいファイルの位置
        moduleAndPkg - ファイルに名前を付ける相対的なモジュールまたはパッケージ(あるいはその両方)、または指定しない場合は空の文字列
        relativeName - ファイルの最終パス名のコンポーネント
        originatingElements - このファイルの作成に因果関係がある型、パッケージまたはモジュール要素、あるいはnull
        戻り値:
        新しいリソースに書き込むためのFileObject
        例外:
        IOException - ファイルを作成できない場合
        FilerException - 同じパス名がすでに作成されている場合、ターゲット・モジュールを判別できない場合、ターゲット・モジュールが書込み可能でない場合、または明示的なターゲット・モジュールが指定されていて、ロケーションでサポートされていない場合。
        IllegalArgumentException - サポートされていない場所の場合
        IllegalArgumentException - moduleAndPkgの形式が正しくない場合
        IllegalArgumentException - relativeNameが相対名でない場合

      • getResource

        FileObject getResource​(JavaFileManager.Location location,
                       CharSequence moduleAndPkg,
                       CharSequence relativeName)
                throws IOException
        既存のリソースを読み取るためのオブジェクトを返します。 場所CLASS_OUTPUTとSOURCE_OUTPUTがサポートされている必要があります。

        moduleAndPkgに/文字が含まれている場合、/文字の前の接頭辞はモジュール名で、/文字の後の接尾辞はパッケージ名です。 パッケージ接尾辞は空でもかまいませんが、モジュール名が存在する場合は空でない必要があります。 moduleAndPkgに/文字が含まれていない場合、引数全体がパッケージ名として解釈されます。

        指定された場所がモジュール指向の場所でも複数のモジュールを含む出力場所でもなく、明示的なモジュール接頭辞が指定されている場合は、FilerExceptionがスローされます。

        指定された場所がモジュール指向の場所か、または複数のモジュールを含む出力場所であり、明示的なモジュール接頭辞が指定されていない場合、適切なモジュールが推測されます。 適切なモジュールを推測できない場合は、FilerExceptionがスローされます。 実装では、推論の一部として注釈処理ツールの構成に関する情報を使用できます。

        実装上のノート:
        リファレンス実装では、注釈処理ツールが単一のモジュールMを処理している場合、明示的なモジュール接頭辞なしで読み取られるファイルのモジュールとしてMが使用されます。 ツールが複数のモジュールを処理していて、Elements.getPackageElement(package-of(name))がパッケージを返した場合、返されたパッケージを所有するモジュールがソース・モジュールとして使用されます。 前述のルールを使用してターゲット・モジュールを決定できない場合は、別のオプションを使用してターゲット・モジュールを提供できます。
        パラメータ:
        location - ファイルの位置
        moduleAndPkg - ファイルを検索する相対的なモジュールまたはパッケージ(あるいはその両方)、あるいはファイルが検索されない場合は空の文字列
        relativeName - ファイルの最終パス名のコンポーネント
        戻り値:
        ファイルを読み取るためのオブジェクト
        例外:
        FilerException - 同じパス名が書込み用にすでにオープンされている場合、ソース・モジュールを決定できない場合、ターゲット・モジュールが書込み可能でない場合、または明示的なターゲット・モジュールが指定されていて、その場所でサポートされていない場合。
        IOException - ファイルを開けない場合
        IllegalArgumentException - サポートされていない場所の場合
        IllegalArgumentException - moduleAndPkgの形式が正しくない場合
        IllegalArgumentException - relativeNameが相対名でない場合