Filer (Java Platform SE 7)

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

バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

インタフェース Filer

メソッドのサマリー

メソッドの詳細

createSourceFile

createClassFile

createResource

getResource