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

インタフェースModuleFinder

public interface ModuleFinder
モジュールのファインダ。 ModuleFinderは、resolutionまたは「サービス・バインディング」の間にモジュールを見つけるために使用されます。

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の場合、同じ名前を持つ2つ以上のモジュールがディレクトリに存在することが含まれます。 エラーが検出されると、これらのメソッドはFindExceptionを適切なcauseでスローします。 FindExceptionがスローされた後のModuleFinderの動作は定義されていません。 たとえば、例外がスローされた後にfindを呼び出すと、例外につながる同じモジュールがスキャンされる場合とされない場合があります。 例外がスローされた後にモジュール・ファインダを破棄することをお勧めします。

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

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

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    static ModuleFinder compose​(ModuleFinder... finders)
    0個以上のモジュール・ファインダのシーケンスから構成されるモジュール・ファインダを返します。
    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が複数回呼び出された場合、毎回同じ(equals)結果が返されます。 返されたセットの各 ModuleReference要素に対して、findがModuleReferenceを見つけてそのモジュールを見つけることが保証されます。

      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ファイルとしてパッケージ化されたモジュールをサポートします。 module-info.classが最上位ディレクトリにあるJARファイル、またはmulti-release JARファイルのバージョニングされたエントリにあるJARファイルは、モジュール式JARファイルであるため、explicitモジュールを定義します。 最上位ディレクトリに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がスローされます。 存在しないファイルへのパスは常に無視されます。

      自動モジュールの場合と同様に、パッケージ化されたモジュールまたは分解されたモジュールの内容は、モジュール内のパッケージを判別するためにscannedである必要があります。 「隠しファイル」が無視されるかどうかは、実装固有であるため、指定されません。 .classファイル( module-info.class以外)が最上位ディレクトリにある場合、名前のないパッケージのクラスとみなされるため、FindExceptionがスローされます。

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

      パラメータ:
      entries - パッケージされたモジュールまたは展開されたモジュールへのモジュールまたはパスのディレクトリへのパスの、おそらく空の配列
      戻り値:
      ファイル・システム上にモジュールを配置するModuleFinder

    • compose

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

      モジュールを見つけると、基礎となるモジュール・ファインダのfindまたはfindAllメソッドによってスローされた例外またはエラーが、結果として得られるモジュール・ファインダfindまたはfindAllメソッドの呼び出し側に伝搬されます。

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