compact3

javax.annotation.processing

インタフェースFiler

public interface Filer

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

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

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

  @Generate
  public class UserSource {}
 

次のように、作成メソッド呼出しの一部としてUserSourceの型要素が渡されるべきです。

      filer.createSourceFile("GeneratedFromUserSource",
                             eltUtils.getTypeElement("UserSource"));
 

作成元要素が存在しない場合は、何も渡す必要がありません。この情報は、インクリメンタル環境で、プロセッサの再実行や生成されたファイルの削除の必要性を判断するために使用される可能性があります。非インクリメンタル環境では、作成元要素の情報は無視されます。

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

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

プロセッサは、ソース・ファイルやクラス・ファイルに@Generated注釈を含めることで、そのファイルが生成されたものであることを示すことができます。

デコレータスタイルのパターンを使えば、ファイルを上書きするのと同じ効果が部分的に得られます。あるクラスを直接変更する代わりに、そのクラスを適切に設計することで、注釈処理によってそのスーパー・クラスまたはサブクラスが生成されるようにします。サブクラスが生成される場合、その親クラスは、publicコンストラクタではなくファクトリを使用するように設計できます。そうすれば、サブクラスのインスタンスのみが、親クラスのクライアントに対して提供されます。

導入されたバージョン:

1.6

メソッドのサマリー

修飾子と型	メソッドと説明
JavaFileObject	createClassFile(CharSequence name, Element... originatingElements) 新しいクラス・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。
FileObject	createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) 書込み対象の新しい補助リソース・ファイルを作成し、それに対応するファイル・オブジェクトを返します。
JavaFileObject	createSourceFile(CharSequence name, Element... originatingElements) 新しいソース・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。
FileObject	getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) 既存のリソースを読み取るためのオブジェクトを返します。

メソッドの詳細

createSourceFile

JavaFileObject createSourceFile(CharSequence name,
                                Element... originatingElements)
                         throws IOException

新しいソース・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。ファイルの名前とパス(ソース・ファイルのルート出力場所に対する相対パス)はそのファイルで宣言される型に基づきます。複数の型が宣言されている場合、主体のトップ・レベル型(public型など)の名前を使用する必要があります。ソース・ファイルは、パッケージ注釈など、パッケージに関する情報の格納用として作成することもできます。名前付きパッケージのソース・ファイルを作成するには、nameをパッケージ名にして、パッケージ名+".package-info"を指定します。名前なしパッケージのソース・ファイルを作成するには、"package-info"を使用します。

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

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

パラメータ:

name - このファイル内で宣言される主体の型の正規の(完全指定)名。パッケージ情報ファイルの場合は、パッケージ名+".package-info"

originatingElements - このファイルの作成に関連付けられる、原因となる型要素またはパッケージ要素。省略可能またはnull

戻り値:

新しいソース・ファイルに書き込むためのJavaFileObject

例外:

FilerException - 同じパス名がすでに作成済みであるか、同じ型がすでに作成済みであるか、または名前が型として有効でない場合

IOException - ファイルを作成できない場合

createClassFile

JavaFileObject createClassFile(CharSequence name,
                               Element... originatingElements)
                        throws IOException

新しいクラス・ファイルを作成し、それへの書込みを可能にするオブジェクトを返します。ファイルの名前とパス(クラス・ファイルのルート出力場所に対する相対パス)は書き込まれる型の名前に基づきます。クラス・ファイルは、パッケージ注釈など、パッケージに関する情報の格納用として作成することもできます。名前付きパッケージのクラス・ファイルを作成するには、nameをパッケージ名にして、パッケージ名+".package-info"を指定します。名前なしパッケージのクラス・ファイルの作成はサポートされていません。

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

パラメータ:

name - 書き込む型のバイナリ名。パッケージ情報ファイルの場合は、パッケージ名+".package-info"

originatingElements - このファイルの作成に関連付けられる、原因となる型要素またはパッケージ要素。省略可能またはnull

戻り値:

新しいクラス・ファイルに書き込むためのJavaFileObject

例外:

FilerException - 同じパス名がすでに作成済みであるか、同じ型がすでに作成済みであるか、または名前が型として有効でない場合

IOException - ファイルを作成できない場合

createResource

FileObject createResource(JavaFileManager.Location location,
                          CharSequence pkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                   throws IOException

書込み対象の新しい補助リソース・ファイルを作成し、それに対応するファイル・オブジェクトを返します。このファイルは、新しく作成されたソース・ファイルやバイナリ・ファイルと一緒に格納することも、サポートされているほかの場所に格納することもできます。場所CLASS_OUTPUTとSOURCE_OUTPUTがサポートされている必要があります。リソースには、ソース・ファイルおよびクラス・ファイルとして一部のパッケージへの相対的なパス名を付けることができます。広い意味では、新しいファイルのフル・パス名は、location、pkg、およびrelativeNameの連結になります。

このメソッド経由で作成されたファイルは、そのファイルの完全パス名がたとえ新しいソース・ファイルやクラス・ファイルの完全パス名に対応している場合でも、注釈処理の対象として登録されません。

パラメータ:

location - 新しいファイルの位置

pkg - ファイルの名前を付ける際に相対パスの基準とすべきパッケージ、ない場合は空文字列

relativeName - ファイルの最終パス名のコンポーネント

originatingElements - このファイルの作成に関連付けられる、原因となる型要素またはパッケージ要素。省略可能またはnull

戻り値:

新しいリソースに書き込むためのFileObject

例外:

IOException - ファイルを作成できない場合

FilerException - 同じパス名がすでに作成済みである場合

IllegalArgumentException - サポートされていない場所の場合

IllegalArgumentException - relativeNameが相対名でない場合

getResource

FileObject getResource(JavaFileManager.Location location,
                       CharSequence pkg,
                       CharSequence relativeName)
                throws IOException

既存のリソースを読み取るためのオブジェクトを返します。場所CLASS_OUTPUTとSOURCE_OUTPUTがサポートされている必要があります。

パラメータ:

location - ファイルの位置

pkg - ファイルを検索する際の基準として使用すべきパッケージ。存在しない場合は空文字列

relativeName - ファイルの最終パス名のコンポーネント

戻り値:

ファイルを読み取るためのオブジェクト

例外:

FilerException - 同じパス名がすでに書込み目的で開かれている場合

IOException - ファイルを開けない場合

IllegalArgumentException - サポートされていない場所の場合

IllegalArgumentException - relativeNameが相対名でない場合