モジュール java.base
パッケージ java.lang.module

インタフェースModuleFinder

  • public interface ModuleFinder
    モジュールのファインダ。 ModuleFinderは、解決またはサービス・バインディング中にモジュールを検索するために使用されます。

    ModuleFinderは、指定された名前のモジュールを1つのみ検索できます。 たとえば、一連のディレクトリ内のモジュールを検索するModuleFinderは、指定された名前のモジュールの最初の出現を検出し、その名前の他のモジュールを無視します。このモジュールは、順序の後続のディレクトリに表示されます。

    使用例: 

    
     Path dir1, dir2, dir3;

     ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);

     Optional<ModuleReference> omref = finder.find("jdk.foo");
     omref.ifPresent(mref -> ... );

    ここで定義したfindメソッドおよびfindAllメソッドは、いくつかの理由で失敗する可能性があります。 これには、I/Oエラー、モジュール記述子(module-info.class)の解析で検出されたエラー、またはModuleFinder.ofによって戻されたModuleFinderの場合、同じ名前の複数のモジュールがディレクトリ内にあることが含まれます。 エラーが検出されると、これらのメソッドはFindExceptionを適切なcauseとともにスローします。 FindExceptionがスローされた後のModuleFinderの動作は未定義です。 たとえば、例外がスローされた後にfindを起動すると、例外が発生するモジュールと同じモジュールがスキャンされる場合とされない場合があります。 例外がスローされた後に、モジュール・ファインダを破棄することをお薦めします。

    ModuleFinderはスレッド・セーフである必要はありません。

    導入されたバージョン:
    9

    • メソッドのサマリー

      すべてのメソッド 静的メソッド インスタンス・メソッド 抽象メソッド
      修飾子と型 メソッド 説明
      static ModuleFinder compose​(ModuleFinder... finders)
      ゼロ個以上のモジュール検索のシーケンスから構成されるモジュール検索を返します。
      Optional<ModuleReference> find​(String name)
      指定された名前のモジュールへの参照を検索します。
      Set<ModuleReference> findAll()
      このファインダが検索できるすべてのモジュール参照のセットを返します。
      static ModuleFinder of​(Path... entries)
      一連のディレクトリまたはパッケージ・モジュール(あるいはその両方)を検索して、ファイル・システム上のモジュールを検索するモジュール・ファインダを返します。
      static ModuleFinder ofSystem()
      システム・モジュールを特定するモジュール・ファインダを返します。

    • メソッドの詳細

      • find

        Optional<ModuleReference> find​(String name)
        指定された名前のモジュールへの参照を検索します。

        ModuleFinderは、特定するモジュールの一貫したビューを提供します。 findを複数回呼び出して同じモジュールを(名前で)検索すると、毎回同じ結果が返されます。 モジュールが配置されている場合は、findAllメソッドによって返される一連のモジュールのメンバーであることが保証されます。

        パラメータ:
        name - 検索するモジュールの名前
        戻り値:
        指定された名前のモジュールへの参照、または見つからない場合は空のOptional
        例外:
        FindException - モジュールの検索中にエラーが発生した場合
        SecurityException - セキュリティ・マネージャによって拒否された場合

      • findAll

        Set<ModuleReference> findAll()
        このファインダが検索できるすべてのモジュール参照のセットを返します。

        ModuleFinderは、特定するモジュールの一貫したビューを提供します。 findAllが複数回呼び出されると、毎回同じ(等しい)結果が返されます。 An exception mapping did not successfully produce and processed a response. Logging the exception propagated to the default exception mapper.

        APIのノート:
        これは、特定のサービスを提供するモジュールを見つけるためにモジュールパスをスキャンする必要がある resolveAndBindなどのメソッドに備えることが重要です。
        戻り値:
        このファインダが検索するすべてのモジュール参照のセット
        例外:
        FindException - すべてのモジュールの検索中にエラーが発生した場合
        SecurityException - セキュリティ・マネージャによって拒否された場合

      • ofSystem

        static ModuleFinder ofSystem()
        システム・モジュールを特定するモジュール・ファインダを返します。 システム・モジュールは、Javaランタイム・イメージ内のモジュールです。 モジュール検索では、常にjava.baseが検索されます。

        セキュリティ・マネージャ・セットがある場合は、そのcheckPermissionメソッドが呼び出され、システム・モジュールにアクセスするためのRuntimePermission("accessSystemModules")がコール元に付与されていることを確認します。

        戻り値:
        システム・モジュールを特定するModuleFinder
        例外:
        SecurityException - セキュリティ・マネージャによって拒否された場合

      • of

        static ModuleFinder of​(Path... entries)
        一連のディレクトリまたはパッケージ・モジュール(あるいはその両方)を検索して、ファイル・システム上のモジュールを検索するモジュール・ファインダを返します。 指定された配列内の各要素は、次のいずれかです。

        1. モジュールのディレクトリへのパス。

        2. 展開されたモジュールの top-levelディレクトリへのパス。

        3. パッケージ・モジュールへのパス。

        モジュールファインダーは、各ディレクトリ、展開済みモジュール、またはパッケージ化されたモジュールを配列のインデックス順に検索してモジュールを見つけます。 指定された名前のモジュールが最初に見つかった場合、そのモジュールのみを使用し、同じ名前の他のモジュールがその後に現れても無視されます。

        要素がモジュールのディレクトリへのパスである場合、ディレクトリ内の各エントリは、パッケージ化されたモジュールまたは展開されたモジュールの最上位ディレクトリです。 ディレクトリに同じ名前の複数のモジュールが含まれている場合は、エラーになります。 要素がディレクトリへのパスであり、そのディレクトリにmodule-info.classという名前のファイルが含まれている場合、そのディレクトリはモジュールのディレクトリではなく展開されたモジュールとして扱われます。

        このメソッドによって返されるモジュール・ファインダでは、JARファイルとしてパッケージ化されたモジュールがサポートされます。 最上位ディレクトリまたはマルチリリースJARファイルのバージョニングされたエントリに module-info.classを含むJARファイルは、モジュラJARファイルであるため、明示的モジュールを定義します。 最上位ディレクトリ内にmodule-info.classがないJARファイルは、自動モジュールを次のように定義します。

        • JARファイルのメイン・マニフェストに属性Automatic-Module-Nameがある場合、その値はモジュール名です。 それ以外の場合、モジュール名はJARファイルの名前から導出されます。

        • versionと、属性"Automatic-Module-Name"が存在しない場合のモジュール名は、次のようにJARファイルのファイル名から導出されます。

          • .jar接尾辞は削除されます。

          • 名前が正規表現 "-(\\d+(\\.|$))" に一致する場合、モジュール名は最初に出現するハイフンより前の部分から導き出されます。 ハイフンの後の部分列は、Versionとして解析され、Versionとして解析できない場合は無視されます。

          • モジュール名内の英数字以外の文字([^A-Za-z0-9])はすべてドット(".")に置き換えられ、すべての繰返しドットは1つのドットに置き換えられ、先頭と末尾のすべてのドットは削除されます。

          • 例えば、「foo-bar.jar」という名前のJARファイルの場合、モジュール名は「foo.bar」となり、バージョンは付与されません。 「foo-bar-1.2.3-SNAPSHOT.jar」という名前のJARファイルの場合、モジュール名は「foo.bar」となり、バージョンは「1.2.3-SNAPSHOT」となります。

        • モジュール内のパッケージのセットは、名前が.classで終わるJARファイル内の非ディレクトリ・エントリから導出されます。 候補パッケージ名は、最後のスラッシュまでの文字を使用して名前から導出されます。ただし、最後のスラッシュは含まれません。 残りのスラッシュはすべてドット(".")で置き換えられます。 結果の文字列が正しいパッケージ名である場合は、パッケージ名とみなされます。 たとえば、JARファイルにエントリ"p/q/Foo.class"が含まれている場合、導出されるパッケージ名は"p.q"です。

        • META-INF/services/で始まるエントリの内容は、サービス構成ファイルとみなされます(ServiceLoaderを参照)。 ファイル名(META-INF/services/の後に続く)が有効なクラス名である場合、その名前はサービス・タイプの完全修飾クラス名とみなされます。 ファイル内のエントリは、プロバイダ・クラスの完全修飾クラス名とみなされます。

        • JARファイルのメイン・マニフェストにMain-Class属性があり、その値が有効なクラス名であり、そのパッケージがそのモジュール用に導出されたパッケージのセット内にある場合、値はモジュールメイン・クラスです。

        自動モジュールのModuleDescriptorを(ModuleDescriptor.Builder APIを使用して)作成できない場合、FindExceptionがスローされます。 これは、Automatic-Module-Name属性の値が有効なモジュール名でない場合に、JARファイルに次のものが含まれているJARファイルのファイル名から有効なモジュール名を導出できない場合に発生することがあります。JARファイルの最上位ディレクトリ内の.class。サービス構成ファイルのエントリが正しいクラス名でないか、そのパッケージ名がモジュール用に導出されたパッケージのセット内にありません。

        JARファイルに加えて、実装によっては他の実装固有のモジュール形式でパッケージ化されたモジュールもサポートされる場合があります。 このメソッドに指定された配列内の要素がモジュールのディレクトリへのパスである場合、そのディレクトリ内のモジュールとして認識されないエントリは無視されます。 配列内の要素が認識されないパッケージ化されたモジュールへのパスである場合、そのファイルが検出された時点でFindExceptionがスローされます。 存在しないファイルへのパスは常に無視されます。

        自動モジュールと同様に、パッケージ化されたモジュールや展開済みモジュールの内容も、そのモジュール内のパッケージを特定するためにスキャンする必要がある場合があります。 隠しファイルが無視されるかどうかは実装に依存しており、そのため仕様では定められていません。 トップレベルディレクトリでmodule-info.class以外の.classファイルが見つかった場合、それは名前なしパッケージ内のクラスであると見なされるため、FindExceptionがスローされます。

        このメソッドで作成されたファインダは遅延しており、指定されたファイル・パスがディレクトリまたはパッケージ・モジュールであることは早急にチェックしません。 したがって、findまたはfindAllメソッドは、これらのメソッドを呼び出すとディレクトリまたはパッケージ化されたモジュールが検索され、エラーが発生した場合にのみ失敗します。

        パラメータ:
        entries - パッケージ化または展開されたモジュールへのモジュールまたはパスのディレクトリへのパスが空である可能性がある配列
        戻り値:
        ファイル・システム上のモジュールを特定するModuleFinder

      • compose

        static ModuleFinder compose​(ModuleFinder... finders)
        ゼロ個以上のモジュール検索のシーケンスから構成されるモジュール検索を返します。 結果のモジュール・ファインダのfindメソッドは、モジュールが見つかるか、またはすべてのモジュール・ファインダーが検索されるまで、各モジュール・ファインダのfindメソッドを配列索引順に呼び出して、モジュールを検索します。 結果のモジュール・ファインダのfindAllメソッドは、最初のモジュール・ファインダによって検出されたすべてのモジュールを含む一連のモジュールを返します。 モジュールのセットには、2番目以降のモジュール・ファインダによって配置されるすべてのモジュールが含まれます。これらのモジュールは、シーケンス内の前のモジュール・ファインダでは配置されません。

        モジュールを検索する場合、基礎となるモジュール・ファインダのfindまたはfindAllメソッドによってスローされた例外またはエラーは、結果のモジュール・ファインダのfindまたはfindAllメソッドのコール元に伝播されます。

        パラメータ:
        finders - モジュール検索の配列
        戻り値:
        一連のモジュール・ファインダを構成するModuleFinder