|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
public interface Filer
このインタフェースは、注釈プロセッサによる新しいファイルの作成をサポートしています。このやり方で作成されたファイルは、このインタフェースを実装している注釈処理ツールに認識され、さらにそのツールで管理されることもできます。そのようにして作成されたソースファイルとクラスファイルは、それらの内容の書き込みに使用された Writer または OutputStream 上で close メソッドが呼び出されると、このツールによって処理対象とみなされます。
区別されるファイルは 3 種類あります。ソースファイル、クラスファイル、および補助リソースファイルです。
新しく作成されたファイルは、2 つのサポートされた位置 (論理ファイルシステム内のサブツリー) に配置されます。1 つは 新しいソースファイル 用、もう 1 つは 新しいクラスファイル 用です。これらの位置は、-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 コンストラクタではなくファクトリを使用するように設計することができます。そうすれば、サブクラスのインスタンスのみが、親クラスのクライアントに対して提供されます。
| メソッドの概要 | |
|---|---|
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)
既存のリソースを読み取るためのオブジェクトを返します。 |
| メソッドの詳細 |
|---|
JavaFileObject createSourceFile(CharSequence name,
Element... originatingElements)
throws IOException
name をパッケージ名にして、パッケージ名＋「.package-info」 を指定します。名前なしパッケージのソースファイルを作成するには、「package-info」 を使用します。
ファイルの内容を特定の 文字セット を使ってエンコードしたい場合は、返されたオブジェクトの OutputStream からその選択された文字セットを持つ OutputStreamWriter を作成できることに注意してください。返されたオブジェクトの Writer を直接使用して書き込みが行われる場合、その文字セットは実装によって決定されます。注釈処理ツールには、これを指定するための -encoding フラグやそれに類するものが用意されている可能性があります。それ以外の場合、それは通常、プラットフォームのデフォルトエンコーディングになります。
後続処理でのエラー発生を防ぐために、この実行で使用されている ソースバージョン に、ソースファイルの内容を準拠させるようにしてください。
name - このファイル内で宣言される主体の型の正規の (完全指定)名。パッケージ情報ファイルの場合は、パッケージ名＋「.package-info」originatingElements - このファイルの作成に関連付けられる、原因となる型要素またはパッケージ要素。省略可能または null
JavaFileObject
FilerException - 同じパス名がすでに作成済みであるか、同じ型がすでに作成済みであるか、または名前が型として有効でない場合
IOException - ファイルを作成できない場合
JavaFileObject createClassFile(CharSequence name,
Element... originatingElements)
throws IOException
name をパッケージ名にして、パッケージ名＋「.package-info」 を指定します。名前なしパッケージのクラスファイルの作成はサポートされていません。
後続処理でのエラー発生を防ぐために、この実行で使用されている ソースバージョン に、クラスファイルの内容を準拠させるようにしてください。
name - 書き込む型のバイナリ名。パッケージ情報ファイルの場合は、パッケージ名＋「.package-info」originatingElements - このファイルの作成に関連付けられる、原因となる型要素またはパッケージ要素。省略可能または null
JavaFileObject
FilerException - 同じパス名がすでに作成済みであるか、同じ型がすでに作成済みであるか、または名前が型として有効でない場合
IOException - ファイルを作成できない場合
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 が相対名でない場合
FileObject getResource(JavaFileManager.Location location,
CharSequence pkg,
CharSequence relativeName)
throws IOException
CLASS_OUTPUT と SOURCE_OUTPUT は必ずサポートされます。
location - ファイルの位置pkg - ファイルを検索する際の基準として使用すべきパッケージ。存在しない場合は空文字列relativeName - ファイルの最終パス名のコンポーネント
FilerException - 同じパス名がすでに書き込み目的で開かれている場合
IOException - ファイルを開けない場合
IllegalArgumentException - サポートされていない場所の場合
IllegalArgumentException - relativeName が相対名でない場合
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。