モジュール 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
        新しいソース・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。 型またはパッケージのソース・ファイルを作成することができます。 ファイル名とパス(「ソース・ファイルのルート出力ロケーション」に関連して)は、ファイル(もしあれば)に指定されたモジュールと同様に、そのファイルで宣言されるアイテムの名前に基づいています。 1つのファイル(つまり、1つのコンパイル単位)で複数の型が宣言されている場合、ファイルの名前は主要なトップレベル型(パブリックなもの、例えば)の名前に対応する必要があります。

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

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

        明示的なモジュール・プレフィクスが与えられておらず、モジュールが環境でサポートされている場合は、適切なモジュールが推測されます。 適切なモジュールが推論できない場合は、FilerExceptionがスローされます。 インプリメンテーションは、推論の一部として注釈処理ツールの構成に関する情報を使用することができます。

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

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

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

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

      • createClassFile

        JavaFileObject createClassFile​(CharSequence name,
                               Element... originatingElements)
                        throws IOException
        新しいクラス・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。 型またはパッケージのクラス・ファイルを作成できます。 ファイル名とパス(「クラス・ファイルのルート出力ロケーション」に関連して)は、宣言されるアイテムの名前と、アイテム(もしあれば)の指定されたモジュールに基づいています。

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

        オプションのモジュール名は、型名またはパッケージ名の前に付けられ、"/"文字を使用して区切られます。 たとえば、モジュールfooに型a.Bのクラス・ファイルを作成するには、"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が相対名でない場合