JavaTM Platform
Standard Ed. 6

javax.tools
インタフェース JavaFileManager

すべてのスーパーインタフェース:
Closeable, Flushable, OptionChecker
既知のサブインタフェースの一覧:
StandardJavaFileManager
既知の実装クラスの一覧:
ForwardingJavaFileManager

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

Java™ プログラミング言語のソースファイルやクラスファイルを操作するツール向けのファイルマネージャーです。このコンテキストでは、「ファイル」という語で、通常ファイルとその他のデータソースを抽象的に表します。

ファイルマネージャーで新しい 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
指定された場所にある、特定のパッケージ内の特定の相対名を表す出力用ファイルオブジェクトを取得します。

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

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

定義:
インタフェース Closeable 内の close
例外:
IOException - 入出力エラーが発生した場合
関連項目:
flush()

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。