モジュール 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ファイルを表す)です。 つまり、元の要素は、「コンパイル・ユニット」 (JLSセクション7.3)の粒度(メソッドやフィールド宣言など、より細かい粒度ではなく、基本的にファイル・レベルの粒度)を持つことを目的としています。

たとえば、ある注釈プロセッサが、次のコードの処理結果として、ソース・ファイル GeneratedFromUserSourceを作成しようとしている場合、 

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

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

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

クラスまたはインタフェースがアクセス可能になるように環境が構成されている場合、プロセッサはGenerated注釈を含めることでソース・ファイルまたはクラス・ファイルが生成されることを示すことができます。

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

  • メソッドの詳細

    • createSourceFile

      JavaFileObject createSourceFile(CharSequence name, Element... originatingElements) throws IOException
      新しいソース・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。 クラス、インタフェースまたはパッケージのソース・ファイルを作成できます。 ファイルの名前とパス(「ソース・ファイルのルート出力ロケーション」に関連して)は、そのファイルで宣言されるアイテムの名前と、アイテム(もしあれば)に指定されたモジュールに基づいています。 複数のクラスまたはインタフェースが単一のファイル(つまり、単一のコンパイル・ユニット)で宣言されている場合、ファイルの名前は、主要な最上位クラスまたはインタフェース(public。例:)の名前に対応している必要があります。

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

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

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

      namedモジュールでの「名前なし」パッケージのソース・ファイルの作成はサポートされていません。

      環境が「名前のないクラス」PREVIEWをサポートするように構成されている場合は、name引数を使用して、出力ファイルに使用される名前の先頭コンポーネントを指定します。 たとえば、filer.createSourceFile("Foo")は、Foo.javaでホストされている名前のないクラスを作成します。 名前のないすべてのクラスは、名前のないパッケージに含まれている必要があります。

      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がスローされます。 実装では、推論の一部として注釈処理ツールの構成に関する情報を使用できます。

      namedモジュールでの「名前なし」パッケージのクラス・ファイルの作成はサポートされていません。

      環境が「名前のないクラス」PREVIEWをサポートするように構成されている場合は、name引数を使用して、出力ファイルに使用される名前の先頭コンポーネントを指定します。 たとえば、filer.createClassFile("Foo")は、Foo.classでホストされている名前のないクラスを作成します。 名前のないすべてのクラスは、名前のないパッケージに含まれている必要があります。

      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が相対名でない場合