JavaFileManager (Java Platform SE 6)

ファイルマネージャーで新しい JavaFileObject を構築する際は、それらをどこに作成するかを指定する必要があります。たとえば、ファイルマネージャーを使ってファイルシステム上の通常ファイルを管理する場合は、現在のディレクトリ (作業ディレクトリ) を、ファイルの作成や検索を行うデフォルトの場所として使用するのが一般的です。ファイルマネージャーには、ファイルの作成場所を示すヒントが多数提供される可能性があります。これらのヒントを無視するように、ファイルマネージャーを設定することもできます。

このインタフェースに含まれる一部のメソッドは、クラス名を使用します。これらのクラス名は、『Java 仮想マシン仕様』で定義されている内部形式で、完全指定のクラス名およびインタフェース名として指定する必要があります。便宜上、「.」と「/」は交換可能です。内部形式の定義については、『Java 仮想マシン仕様』の第 4 章を参照してください。

解説: この場合、「java/lang.package-info」、「java/lang/package-info」、「java.lang.package-info」の 3 種類の名前がすべて有効で、等価であることになります。『Java 言語仕様 (JLS)』のセクション 13.1「The Form of a Binary」に定義されたバイナリ名と比較してください。

名前の大文字と小文字を正しく区別する必要があります。すべての名前の大文字と小文字が区別されます。たとえば、ファイル名の大文字と小文字の区別は行わないが、その違いを認識するファイルシステムがあるとします。この場合、File.getCanonicalFile() または同様の手段を使って、ファイルオブジェクト (ファイルを表す) の大文字と小文字の区別を保持するようにします。システムが大文字と小文字の区別を認識しない場合は、その他の手段で、ファイルオブジェクトの大文字と小文字の区別を保持する必要があります。

相対名:このインタフェースに含まれる一部のメソッドは、相対名を使用します。相対名は、一連のパスセグメント (null 以外、空以外) を「/」で区切った形式の名前です。「.」または「..」は無効なパスセグメントです。有効な相対名は、RFC 3986 のセクション 3.3 に定義されている「path-rootless」の規則に準拠している必要があります。非公式には、次の条件が true になるようにします。

  URI.create(relativeName).normalize().getPath().equals(relativeName)

このインタフェースに含まれるすべてのメソッドは、SecurityException をスローする可能性があります。

このインタフェースのオブジェクトは、マルチスレッドアクセスをサポートしていなくてもかまいません。つまり、同期化は必要ありません。ただし、このオブジェクトによって作成された複数のファイルオブジェクトへの並行アクセスはサポートしている必要があります。

実装にあたっての注意: この要件があるため、JarOutputStream への出力の単純な実装では、実装として不十分です。そこで、JarOutputStream を直接返す JavaFileObject を作成するのではなく、コンテンツをキャッシュに格納し、終了したら JarOutputStream に書き込むようにします。

明示的に許可されていない場合に引数として null が指定されると、このインタフェースに含まれるすべてのメソッドは NullPointerException をスローする可能性があります。

導入されたバージョン:: 1.6
関連項目:: JavaFileObject, FileObject

入れ子のクラスの概要
`static interface`	`JavaFileManager.Location` ファイルオブジェクトの場所のインタフェースです。

メソッドの概要
`void`	`close()` このファイルマネージャーによって直接的または間接的に開かれたリソースがあれば、それを解放します。
`void`	`flush()` このファイルマネージャーによって直接的または間接的に開かれた出力用リソースがあれば、それをフラッシュします。
`ClassLoader`	`getClassLoader(JavaFileManager.Location location)` 指定された場所からプラグインをロードするクラスローダーを取得します。
`FileObject`	`getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)` 指定された場所にある、特定のパッケージ内の特定の相対名を表す入力用ファイルオブジェクトを取得します。
`FileObject`	`getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)` 指定された場所にある、特定のパッケージ内の特定の相対名を表す出力用ファイルオブジェクトを取得します。
`JavaFileObject`	`getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)` 指定された場所にある、特定の種類の特定のクラスを表す入力用ファイルオブジェクトを取得します。
`JavaFileObject`	`getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)` 指定された場所にある、特定の種類の特定のクラスを表す出力用ファイルオブジェクトを取得します。
`boolean`	`handleOption(String current, Iterator<String> remaining)` 1 つのオプションを処理します。
`boolean`	`hasLocation(JavaFileManager.Location location)` このファイルマネージャーにとって既知の場所であるかどうかを判断します。
`String`	`inferBinaryName(JavaFileManager.Location location, JavaFileObject file)` 場所に基づいてファイルオブジェクトのバイナリ名を推測します。
`boolean`	`isSameFile(FileObject a, FileObject b)` 2 つのファイルオブジェクトを比較し、これらによって表される配下のオブジェクトが同じである場合は true を返します。
`Iterable<JavaFileObject>`	`list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)` 指定の場所の指定の基準に一致するすべてのファイルオブジェクトを一覧表示します。

インタフェース javax.tools.OptionChecker から継承されたメソッド
`isSupportedOption`

メソッドの詳細

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

指定された場所からプラグインをロードするクラスローダーを取得します。たとえば、注釈プロセッサをロードする場合、コンパイラは ANNOTATION_PROCESSOR_PATH のクラスローダーを要求します。

パラメータ:: location - 場所
戻り値:: 指定の場所のクラスローダー。指定の場所からプラグインをロードできない場合、または未知の場所が指定された場合は null
例外:: SecurityException - 現在のセキュリティーコンテキストでクラスローダーを作成できない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

list

Iterable<JavaFileObject> list(JavaFileManager.Location location,
                              String packageName,
                              Set<JavaFileObject.Kind> kinds,
                              boolean recurse)
                              throws IOException

指定の場所の指定の基準に一致するすべてのファイルオブジェクトを一覧表示します。再帰処理が有効になっている場合、「サブパッケージ」内のファイルオブジェクトも一覧表示されます。

注:このファイルマネージャーにとって未知の場所が指定された場合も、null が返されることはありません。また、例外が生成されることもありません。

パラメータ:: location - 場所; packageName - パッケージ名; kinds - これらの種類のオブジェクトのみ返す; recurse - true の場合、「サブパッケージ」も含まれる
戻り値:: 指定された基準に一致するファイルオブジェクトの Iterable
例外:: IOException - 入出力エラーが発生した場合、または close() が呼び出され、このファイルマネージャーを再度開くことができない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)

場所に基づいてファイルオブジェクトのバイナリ名を推測します。有効な JLS バイナリ名でないバイナリ名が返される場合もあります。

パラメータ:: location - 場所; file - ファイルオブジェクト
戻り値:: バイナリ名。指定された場所にファイルオブジェクトが見つからない場合は null
例外:: IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)

2 つのファイルオブジェクトを比較し、これらによって表される配下のオブジェクトが同じである場合は true を返します。

パラメータ:: a - ファイルオブジェクト; b - ファイルオブジェクト
戻り値:: 指定されたファイルオブジェクトによって表される配下のオブジェクトが同じである場合は true
例外:: IllegalArgumentException - どちらかの引数が別のファイルマネージャーで作成された引数であり、このファイルマネージャーが外部ファイルオブジェクトをサポートしていない場合

handleOption

boolean handleOption(String current,
                     Iterator<String> remaining)

1 つのオプションを処理します。current がこのファイルマネージャーのオプションである場合は、remaining からそのオプションに対するすべての引数を使用し、true を返します。そうでない場合は false を返します。

パラメータ:: current - 現在のオプション; remaining - 残りのオプション
戻り値:: このオプションがこのファイルマネージャーで処理された場合は true、そうでない場合は false
例外:: IllegalArgumentException - このファイルマネージャーに対するこのオプションが不正に使用された場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

hasLocation

boolean hasLocation(JavaFileManager.Location location)

このファイルマネージャーにとって既知の場所であるかどうかを判断します。

パラメータ:: location - 場所
戻り値:: 既知の場所である場合は true

getJavaFileForInput

JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                   String className,
                                   JavaFileObject.Kind kind)
                                   throws IOException

指定された場所にある、特定の種類の特定のクラスを表す入力用ファイルオブジェクトを取得します。

パラメータ:: location - 場所; className - クラスの名前; kind - ファイルの種類。SOURCE または CLASS
戻り値:: ファイルオブジェクト。ファイルが存在しない場合は null が返される可能性がある
例外:: IllegalArgumentException - このファイルマネージャーにとって未知の場所が指定され、ファイルマネージャーが未知の場所をサポートしていない場合、またはファイルの種類が有効でない場合; IOException - 入出力エラーが発生した場合、または close() が呼び出され、このファイルマネージャーを再度開くことができない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

getJavaFileForOutput

JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                    String className,
                                    JavaFileObject.Kind kind,
                                    FileObject sibling)
                                    throws IOException

指定された場所にある、特定の種類の特定のクラスを表す出力用ファイルオブジェクトを取得します。

このファイルマネージャーは、オプションとして、兄弟ウィジェットを出力先のヒントとして使用する可能性があります。このヒントの厳密なセマンティクスは指定されません。たとえば Sun のコンパイラ javac は、クラスファイルの出力ディレクトリが指定されていない場合、ソースファイルと同じディレクトリにクラスファイルを配置します。この処理を簡便化するため、javac は、このメソッドを呼び出すとき、ソースファイルを兄弟ウィジェットとして指定することがあります。

パラメータ:: location - 場所; className - クラスの名前; kind - ファイルの種類。SOURCE または CLASS; sibling - 配置のヒントとして使用されるファイルオブジェクト。null も可
戻り値:: 出力用ファイルオブジェクト
例外:: IllegalArgumentException - このファイルマネージャーにとって未知の兄弟ウィジェットが指定された場合、このファイルマネージャーにとって未知の場所が指定され、ファイルマネージャーが未知の場所をサポートしていない場合、またはファイルの種類が有効でない場合; IOException - 入出力エラーが発生した場合、または close() が呼び出され、このファイルマネージャーを再度開くことができない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

getFileForInput

FileObject getFileForInput(JavaFileManager.Location location,
                           String packageName,
                           String relativeName)
                           throws IOException

指定された場所にある、特定のパッケージ内の特定の相対名を表す入力用ファイルオブジェクトを取得します。

返されたオブジェクトがソースファイルまたはクラスファイルを表す場合、JavaFileObject のインスタンスである必要があります。

非公式には、このメソッドで返されるファイルオブジェクトは、場所、パッケージ名、および相対名を連結した場所にあります。たとえば、SOURCE_PATH にある com.sun.tools.javac パッケージ内のプロパティーファイル resources/compiler.properties を探している場合、次のようにしてこのメソッドを呼び出すことができます。

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

この呼び出しが Windows 上で実行され、SOURCE_PATH が "C:\Documents and Settings\UncleBob\src\share\classes" に設定されていた場合、有効な結果は、ファイル "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties" を表すファイルオブジェクトになります。

パラメータ:: location - 場所; packageName - パッケージ名; relativeName - 相対名
戻り値:: ファイルオブジェクト。ファイルが存在しない場合は null が返される可能性がある
例外:: IllegalArgumentException - このファイルマネージャーにとって未知の場所が指定され、ファイルマネージャーが未知の場所をサポートしていない場合、または relativeName が有効でない場合; IOException - 入出力エラーが発生した場合、または close() が呼び出され、このファイルマネージャーを再度開くことができない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

getFileForOutput

FileObject getFileForOutput(JavaFileManager.Location location,
                            String packageName,
                            String relativeName,
                            FileObject sibling)
                            throws IOException

指定された場所にある、特定のパッケージ内の特定の相対名を表す出力用ファイルオブジェクトを取得します。

返されたオブジェクトがソースファイルまたはクラスファイルを表す場合、JavaFileObject のインスタンスである必要があります。

非公式には、このメソッドで返されるファイルオブジェクトは、場所、パッケージ名、および相対名を連結した場所か、兄弟引数の次にあります。例は、getFileForInput を参照してください。

パラメータ:: location - 場所; packageName - パッケージ名; relativeName - 相対名; sibling - 配置のヒントとして使用されるファイルオブジェクト。null も可
戻り値:: ファイルオブジェクト
例外:: IllegalArgumentException - このファイルマネージャーにとって未知の兄弟ウィジェットが指定された場合、このファイルマネージャーにとって未知の場所が指定され、ファイルマネージャーが未知の場所をサポートしていない場合、または relativeName が有効でない場合; IOException - 入出力エラーが発生した場合、または close() が呼び出され、このファイルマネージャーを再度開くことができない場合; IllegalStateException - close() が呼び出され、このファイルマネージャーを再度開くことができない場合

flush

void flush()
           throws IOException

このファイルマネージャーによって直接的または間接的に開かれた出力用リソースがあれば、それをフラッシュします。閉じられたファイルマネージャーをフラッシュしても、効果はありません。

定義:: インタフェース Flushable 内の flush

例外:: IOException - 入出力エラーが発生した場合
関連項目:: close()

close

void close()
           throws IOException

このファイルマネージャーによって直接的または間接的に開かれたリソースがあれば、それを解放します。すると、このファイルマネージャーが無効になり、その後このオブジェクト上で行われるメソッド呼び出しや、このオブジェクトを通して取得されるオブジェクトは、明示的に許可されていないかぎり未定義になります。ただし、すでに閉じられたファイルマネージャーを閉じても、効果はありません。