モジュール 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などの既存のクラスまたはインタフェースに対応するファイルを開こうとする試みを拒否する場合があります。 同様に、注釈処理ツールの呼出し元は、生成されたものではない既存ファイルの上書きを検出されたプロセッサが試みるように、ツールを故意に構成してはいけません。

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

APIのノート:
ファイルの上書きの効果の一部は、decoratorスタイルのパターンを使用することによって達成できます。 あるクラスを直接変更する代わりに、そのクラスを適切に設計することで、注釈処理によってそのスーパー・クラスまたはサブクラスが生成されるようにします。 サブクラスが生成される場合、その親クラスは、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モジュールでの「名前なし」パッケージのソース・ファイルの作成はサポートされていません。

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

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