モジュール 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
外部仕様