モジュール 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ファイルとしてパッケージ化されたモジュールをサポートします。 最上位ディレクトリまたはmulti-release JARファイル内のバージョン管理されたエントリに module-info.classを含む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