インタフェースJavaFileManager

すべてのスーパー・インタフェース:
AutoCloseable, Closeable, Flushable, OptionChecker
既知のすべてのサブインタフェース:
StandardJavaFileManager
既知のすべての実装クラス:
ForwardingJavaFileManager
public interface JavaFileManager extends Closeable, Flushable, OptionChecker
Javaプログラミング言語のソース・ファイルおよびクラス・ファイルで動作するツールのファイル・マネージャ。 このコンテキストでは、ファイルという語で、通常ファイルとその他のデータ・ソースを抽象的に表します。

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

このインタフェースに含まれる一部のメソッドは、クラス名を使用します。 これらのクラス名は、『Java仮想マシン仕様』で定義されている内部形式で、完全指定のクラス名およびインタフェース名として指定する必要があります。 便宜上、'.'と'/'は交換可能です。 内部フォームは、「Java Virtual Machine仕様」の第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)

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

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

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

導入されたバージョン:
1.6
外部仕様
関連項目:

  • メソッドの詳細

    • getClassLoader

      ClassLoader getClassLoader(JavaFileManager.Location location)
      指定されたパッケージ指向のロケーションからプラグインをロードするためのクラス・ローダーを返します。 たとえば、注釈プロセッサをロードするには、コンパイラは、ANNOTATION_PROCESSOR_PATHの場所のクラス・ローダーを要求します。
      パラメータ:
      location - 場所
      戻り値:
      指定の場所のクラス・ローダー。指定の場所からプラグインをロードできない場合、または未知の場所が指定された場合はnull
      スロー:
      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()が呼び出され、このファイル・マネージャを再度開くことができない場合

    • getJavaFileForOutputForOriginatingFiles

      default JavaFileObject getJavaFileForOutputForOriginatingFiles(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject... originatingFiles) throws IOException
      指定されたパッケージ指向のロケーションで、指定された種類の指定されたクラスを表す出力の「ファイル・オブジェクト」を返します。

      提供されているoriginatingFilesは、このメソッドによって作成されたファイルのコンテンツの作成に使用された、不特定の方法で行われたファイルを表します。 originatingElements in Filer.createSourceFile(java.lang.CharSequence, javax.lang.model.element.Element...)を参照してください。 Elements.getFileObjectOf(javax.lang.model.element.Element)を使用して、ElementをFileObjectに変換できます。

      実装要件:
      デフォルトの実装では、originatingFilesの最初の要素(ある場合)をsiblingとしてgetJavaFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, javax.tools.JavaFileObject.Kind, javax.tools.FileObject)をコールします。
      パラメータ:
      location - パッケージ志向のロケーション
      className - クラスの名前
      kind - ファイルの種類。SOURCEまたはCLASSのいずれかである必要がある
      originatingFiles - この新しく作成されたファイルに寄与するファイル。nullは空のoriginatingFilesと同等で、既知の元のファイルがないことを意味
      戻り値:
      出力用ファイル・オブジェクト
      スロー:
      IllegalArgumentException - 兄弟がこのファイル・マネージャに知られていない場合、またはロケーションがこのファイル・マネージャに知られておらず、ファイル・マネージャが不明なロケーションをサポートしていない場合、または種類が有効でない場合、またはロケーションが出力ロケーションでない場合
      IOException - 入出力エラーが発生した場合、またはclose()が呼び出され、このファイル・マネージャを再度開くことができない場合
      IllegalStateException - close()が呼び出され、このファイル・マネージャを再度開くことができない場合
      導入されたバージョン:
      18
      関連項目:

    • 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()が呼び出され、このファイル・マネージャを再度開くことができない場合

    • getFileForOutputForOriginatingFiles

      default FileObject getFileForOutputForOriginatingFiles(JavaFileManager.Location location, String packageName, String relativeName, FileObject... originatingFiles) throws IOException
      指定されたロケーションにある指定されたパッケージ内の指定された「相対名」を表す出力の「ファイル・オブジェクト」を返します。

      提供されているoriginatingFilesは、このメソッドによって作成されたファイルのコンテンツの作成に使用された、不特定の方法で行われたファイルを表します。 originatingElements in Filer.createResource(javax.tools.JavaFileManager.Location, java.lang.CharSequence, java.lang.CharSequence, javax.lang.model.element.Element...)を参照してください。 Elements.getFileObjectOf(javax.lang.model.element.Element)を使用して、ElementをFileObjectに変換できます。

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

      このメソッドによって返されるファイル・オブジェクトは、ロケーション、パッケージ名および相対名、またはoriginatingFilesから推測されるロケーションの連結にあります。 例については、getFileForInputを参照してください。

      実装要件:
      デフォルトの実装では、originatingFilesの最初の要素(ある場合)をsiblingとしてgetFileForOutput(javax.tools.JavaFileManager.Location, java.lang.String, java.lang.String, javax.tools.FileObject)をコールします。
      パラメータ:
      location - 出力ロケーション
      packageName - パッケージ名
      relativeName - 相対名
      originatingFiles - この新しく作成されたファイルに寄与するファイル。nullは空のoriginatingFilesと同等で、既知の元のファイルがないことを意味
      戻り値:
      ファイル・オブジェクト
      スロー:
      IllegalArgumentException - このファイル・マネージャで兄弟が認識されていない場合、またはこのファイル・マネージャでロケーションが認識されておらず、ファイル・マネージャが不明なロケーションをサポートしていない場合、またはrelativeNameが有効でない場合、またはロケーションが出力ロケーションでない場合
      IOException - 入出力エラーが発生した場合、またはclose()が呼び出され、このファイル・マネージャを再度開くことができない場合
      IllegalStateException - close()が呼び出され、このファイル・マネージャを再度開くことができない場合
      導入されたバージョン:
      18
      関連項目:

    • flush

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

    • close

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

    • 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