モジュール java.compiler
パッケージ javax.tools

インタフェースJavaFileManager

すべてのスーパー・インタフェース:
AutoCloseable, 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™言語仕様』のセクション13.1「バイナリの形式」に定義されたバイナリ名と比較してください。

名前の大文字と小文字を正しく区別する必要があります。 すべての名前の大文字と小文字が区別されます。 たとえば、ファイル名の大文字と小文字の区別は行わないが、その違いを認識するファイル・システムがあるとします。 この場合、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

  • メソッドの詳細

    • getClassLoader

      ClassLoader getClassLoader​(JavaFileManager.Location location)
      指定されたパッケージ指向のロケーションからプラグインをロードするためのクラス・ローダーを返します。 たとえば、注釈プロセッサをロードするには、コンパイラは、ANNOTATION_PROCESSOR_PATHの場所のクラス・ローダーを要求します。
      パラメータ:
      location - 場所
      戻り値:
      指定の場所のクラス・ローダー。指定の場所からプラグインをロードできない場合、または未知の場所が指定された場合はnull
      例外:
      SecurityException - 現在のセキュリティ・コンテキストでクラス・ローダーを作成できない場合
      IllegalStateException - close()が呼び出され、このファイル・マネージャを再度開くことができない場合
      IllegalArgumentException - ロケーションがモジュール指向のロケーションである場合

    • 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()が呼び出され、このファイル・マネージャを再度開くことができない場合
      IllegalArgumentException - ロケーションがモジュール指向のロケーションである場合
      IllegalStateException - close()が呼び出され、このファイル・マネージャを再度開くことができない場合

    • inferBinaryName

      String inferBinaryName​(JavaFileManager.Location location, JavaFileObject file)
      パッケージ指向のロケーションに基づいてファイル・オブジェクトのバイナリ名を推論します。 返されるバイナリ名は、『Java™言語仕様』に従った有効なバイナリ名ではないことがあります。
      パラメータ:
      location - 場所
      file - ファイル・オブジェクト
      戻り値:
      バイナリ名。指定された場所にファイル・オブジェクトが見つからない場合はnull
      例外:
      IllegalArgumentException - ロケーションがモジュール指向のロケーションである場合
      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
      指定されたパッケージ指向のロケーションで指定された種類の指定されたクラスを表す出力用の「ファイル・オブジェクト」を返します。

      このファイル・マネージャは、オプションとして、兄弟ウィジェットを出力先のヒントとして使用する可能性があります。 このヒントの厳密なセマンティックスは指定されません。 たとえばJDKコンパイラ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
      指定されたロケーションの指定されたパッケージ内の指定された「相対名」を表す出力用の「ファイル・オブジェクト」を返します。

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

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

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

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

    • flush

      void flush() throws IOException
      このファイル・マネージャによって直接的または間接的に開かれた出力用リソースがあれば、それをフラッシュします。 閉じられたファイル・マネージャをフラッシュしても、効果はありません。
      定義:
      flush、インタフェース: Flushable
      例外:
      IOException - 入出力エラーが発生した場合
      関連項目:
      close()

    • close

      void close() throws IOException
      このファイル・マネージャによって直接的または間接的に開かれたリソースがあれば、それを解放します。 すると、このファイル・マネージャが無効になり、その後このオブジェクト上で行われるメソッド呼び出しや、このオブジェクトを通して取得されるオブジェクトは、明示的に許可されていないかぎり未定義になります。 ただし、すでに閉じられたファイル・マネージャを閉じても、効果はありません。
      定義:
      close、インタフェース: AutoCloseable
      定義:
      close、インタフェース: Closeable
      例外:
      IOException - 入出力エラーが発生した場合
      関連項目:
      flush()

    • getLocationForModule

      default JavaFileManager.Location getLocationForModule​(JavaFileManager.Location location, String moduleName) throws IOException
      モジュール指向のロケーションまたは出力ロケーションのいずれかである、ロケーション内の名前付きモジュールのロケーションを取得します。 指定されたロケーションが出力ロケーションである場合、結果が出力ロケーションになります。またはパッケージ指向のロケーションになります。
      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      パラメータ:
      location - モジュール指向のロケーション
      moduleName - 見つかるモジュールの名前
      戻り値:
      指定されたモジュールのロケーション
      例外:
      IOException - 入出力エラーが発生した場合
      UnsupportedOperationException - この操作がこのファイル・マネージャでサポートされていない場合
      IllegalArgumentException - そのロケーションが出力ロケーションでもモジュール指向のロケーションでもない場合
      導入されたバージョン:
      9

    • getLocationForModule

      default JavaFileManager.Location getLocationForModule​(JavaFileManager.Location location, JavaFileObject fo) throws IOException
      特定のファイルが格納されているモジュールのロケーションを取得します。ロケーションは、モジュール指向のロケーションまたは出力ロケーションのいずれかです。 指定されたロケーションが出力ロケーションである場合、結果が出力ロケーションになります。またはパッケージ指向のロケーションになります。
      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      パラメータ:
      location - モジュール指向のロケーション
      fo - ファイル
      戻り値:
      ファイルを含むモジュール
      例外:
      IOException - 入出力エラーが発生した場合
      UnsupportedOperationException - この操作がこのファイル・マネージャでサポートされていない場合
      IllegalArgumentException - そのロケーションが出力ロケーションでもモジュール指向のロケーションでもない場合
      導入されたバージョン:
      9

    • getServiceLoader

      default <S> ServiceLoader<S> getServiceLoader​(JavaFileManager.Location location, Class<S> service) throws IOException
      指定されたロケーションから特定のサービス・クラスのサービス・ローダーを取得します。 ロケーションがモジュール指向のロケーションである場合、サービス・ローダーはそのロケーションにあるモジュール内のサービス宣言を使用します。 それ以外の場合は、パッケージ指向のロケーションを使用してサービス・ローダーが作成されます。この場合、サービスはMETA-INF/servicesのプロバイダ構成ファイルを使用して決定されます。
      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      型パラメータ:
      S - サービス・クラス
      パラメータ:
      location - モジュール指向のロケーション
      service - サービス・クラスのClassオブジェクト
      戻り値:
      指定されたサービス・クラスのサービス・ローダー
      例外:
      IOException - 入出力エラーが発生した場合
      UnsupportedOperationException - この操作がこのファイル・マネージャでサポートされていない場合
      導入されたバージョン:
      9

    • inferModuleName

      default String inferModuleName​(JavaFileManager.Location location) throws IOException
      getLocationForModuleまたはlistModuleLocationsから返されるモジュールの名前をそのロケーションから推測します。
      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      パラメータ:
      location - モジュールを表すパッケージ指向のロケーション
      戻り値:
      モジュールの名前
      例外:
      IOException - 入出力エラーが発生した場合
      UnsupportedOperationException - この操作がこのファイル・マネージャでサポートされていない場合
      IllegalArgumentException - そのロケーションがこのファイル・マネージャに知られていない場合
      導入されたバージョン:
      9

    • listLocationsForModules

      default Iterable<Set<JavaFileManager.Location>> listLocationsForModules​(JavaFileManager.Location location) throws IOException
      モジュール指向のロケーションまたは出力ロケーションのすべてのモジュールのロケーションを一覧表示します。 指定されたロケーションが出力である場合、またはパッケージ指向のロケーションになる場合、返されるロケーションは出力ロケーションになります。
      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      パラメータ:
      location - モジュールをリストするモジュール指向のロケーション
      戻り値:
      モジュールを含む一連のロケーションのセット
      例外:
      IOException - 入出力エラーが発生した場合
      UnsupportedOperationException - この操作がこのファイル・マネージャでサポートされていない場合
      IllegalArgumentException - ロケーションがモジュール指向のロケーションでない場合
      導入されたバージョン:
      9

    • contains

      default boolean contains​(JavaFileManager.Location location, FileObject fo) throws IOException
      指定されたファイル・オブジェクトが指定されたロケーション"に含まれた"かどうかを決定します。

      パッケージ指向のロケーションでは、packageNameとrelativeNameの値が存在する場合、次の呼び出しのいずれかがsameファイル・オブジェクトを返すようにファイル・オブジェクトが格納されます: 

           getFileForInput(location, packageName, relativeName)
     getFileForOutput(location, packageName, relativeName, null)

      モジュール指向のロケーションでは、呼び出しによって取得される可能性のあるモジュールが存在する場合、ファイル・オブジェクトがそのロケーションに格納されます: 

           getLocationForModule(location, moduleName)
      そのファイル・オブジェクトは、そのモジュールの(package-oriented)のロケーションに格納されます。

      実装要件:
      この実装はUnsupportedOperationExceptionをスローします。
      パラメータ:
      location - ロケーション
      fo - ファイル・オブジェクト
      戻り値:
      ファイルがそのロケーションに含まれているかどうか
      例外:
      IOException - 結果を決定する際に問題がある場合
      UnsupportedOperationException - メソッドがサポートされていない場合
      導入されたバージョン:
      9