模块  java.base
软件包  java.lang.module

Interface ModuleFinder


  • public interface ModuleFinder
    模块的发现者。 ModuleFinder用于在resolutionservice binding期间查找模块。

    A ModuleFinder只能找到一个具有给定名称的模块。 例如,在一系列目录中查找模块的ModuleFinder将找到给定名称的模块的第一次出现,并将忽略序列中稍后出现在目录中的该名称的其他模块。

    用法示例:

       Path dir1, dir2, dir3; ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3); Optional<ModuleReference> omref = finder.find("jdk.foo"); omref.ifPresent(mref -> ... );  

    此处定义的findfindAll方法可能由于多种原因而失败。 这些包括I / O错误,检测到解析模块描述符的错误( module-info.class ),或者在ModuleFinder返回的ModuleFinder的情况下,在目录中找到两个或多个具有相同名称的模块。 当检测到错误时,这些方法抛出FindException并使用适当的cause 抛出ModuleFinder之后FindException的行为未定义。 例如,在抛出异常后调用find可能会也可能不会扫描导致异常的相同模块。 建议在抛出异常后丢弃模块查找器。

    ModuleFinder不需要是线程安全的。

    从以下版本开始:
    9
    • 方法详细信息

      • find

        Optional<ModuleReference> find​(String name)
        查找对给定名称的模块的引用。

        A ModuleFinder提供了它所找到的模块的一致视图。 如果find调用find以查找相同的模块(按名称),则每次都会返回相同的结果。 如果找到模块,则保证它是findAll方法返回的模块集的成员。

        参数
        name - 要查找的模块的名称
        结果
        对具有给定名称的模块的引用,如果未找到 OptionalOptional
        异常
        FindException - 如果找到模块时发生错误
        SecurityException - 如果安全经理拒绝
      • findAll

        Set<ModuleReference> findAll()
        返回此finder可以找到的所有模块引用的集合。

        A ModuleFinder提供了它所找到的模块的一致视图。 如果多次调用findAll则每次都会返回相同(等于)的结果。 对于返回集中的每个ModuleReference元素,保证find将在调用时找到ModuleReference以查找该模块。

        API Note:
        这对于需要扫描模块路径以查找提供特定服务的模块的方法(例如 resolveAndBind )非常重要。
        结果
        此查找程序所在的所有模块引用的集合
        异常
        FindException - 如果发现所有模块时发生错误
        SecurityException - 如果安全经理拒绝
      • ofSystem

        static ModuleFinder ofSystem()
        返回定位系统模块的模块查找器。 系统模块是Java运行时映像中的模块。 模块查找器将始终找到java.base

        如果存在安全管理器集,则调用其checkPermission方法以检查调用者是否已被授予RuntimePermission("accessSystemModules")以访问系统模块。

        结果
        用于定位系统模块的 ModuleFinder
        异常
        SecurityException - 如果安全经理拒绝
      • of

        static ModuleFinder of​(Path... entries)
        返回一个模块查找器,它通过搜索一系列目录和/或打包模块来定位文件系统上的模块。 给定数组中的每个元素都是以下之一:
        1. 模块目录的路径。

        2. 分解模块顶级目录的路径。

        3. 打包模块的路径。

        模块查找器通过以数组索引顺序搜索每个目录,爆炸模块或打包模块来查找模块。 它找到第一次出现具有给定名称的模块,并忽略序列中稍后出现的该名称的其他模块。

        如果元素是模块目录的路径,则目录中的每个条目都是打包模块或爆炸模块的顶级目录。 如果目录包含多个具有相同名称的模块,则会出错。 如果元素是目录的路径,并且该目录包含名为module-info.class的文件,则该目录将被视为爆炸模块而不是模块目录。

        此方法返回的模块查找器支持打包为JAR文件的模块。 用一个JAR文件module-info.class在其顶层目录,或在在一个版本条目multi-release JAR文件,是一个模块化的JAR文件,从而定义了一个明确的模块。 在其顶级目录中没有module-info.class JAR文件定义了一个自动模块 ,如下所示:

        • 如果JAR文件在其主清单中具有属性“ Automatic-Module-Name ”,则其值为module name 否则,模块名称是从JAR文件的名称派生的。

        • version和属性“ Automatic-Module-Name ”不存在时的模块名称是从JAR文件的文件名派生的,如下所示:

          • 删除“ .jar ”后缀。

          • 如果名称与正则表达式"-(\\d+(\\.|$))"匹配,则模块名称将从第一次出现的连字符之前的子序列派生。 连字符后面的子序列被解析为Version ,如果无法解析为Version ,则忽略该子Version

          • 模块名称中的所有非字母数字字符( [^A-Za-z0-9] )将替换为点( "." ),所有重复点均替换为一个点,并删除所有前导点和尾随点。

          • 例如,名为“ foo-bar.jar ”的JAR文件将派生模块名称“ foo.bar ”,而不是版本。 名为“ foo-bar-1.2.3-SNAPSHOT.jar ”的JAR文件将导出模块名称“ foo.bar ”和“ 1.2.3-SNAPSHOT ”作为版本。

        • 模块中的程序包集合源自JAR文件中名称以“ .class ”结尾的非目录条目。 候选包名称是使用最后一个正斜杠所包含但不包括的字符从名称派生的。 所有剩余的正斜线都用点( "." )替换。 如果生成的字符串是合法的包名称,则假定它是包名称。 例如,如果JAR文件包含条目“ p/q/Foo.class ”,则派生的包名称为“ p.q ”。

        • META-INF/services/开头的条目内容假定为服务配置文件(请参阅ServiceLoader )。 如果文件名(在META-INF/services/ )是合法的类名,则假定它是服务类型的完全限定类名。 假定文件中的条目是提供者类的完全限定类名。

        • 如果JAR文件的主清单中有Main-Class属性,则其值为合法类名,并且其包位于为模块派生的包集中,则值为模块main class

        如果无法为自动模块创建ModuleDescriptor (通过ModuleDescriptor.Builder API),则抛出FindException 当“ Automatic-Module-Name ”属性的值不是合法模块名称时,可能会出现这种情况,无法从JAR文件的文件名派生合法模块名称,其中JAR文件在顶级目录中包含.class 。 JAR文件,其中服务配置文件中的条目不是合法类名称或其包名称不在为模块派生的包集合中。

        除了JAR文件之外,实现还可以支持以其他实现特定模块格式打包的模块。 如果为此方法指定的数组中的元素是模块目录的路径,则忽略目录中未识别为模块的条目。 如果数组中的元素是未识别的打包模块的路径,则在遇到文件时会抛出FindException 始终忽略不存在的文件的路径。

        与自动模块一样,可能需要扫描打包或分解模块的内容以确定模块中的包。 是否忽略hidden files是特定于实现的,因此未指定。 如果在顶级目录中找到.class文件( module-info.class ),则假定它是未命名包中的类,因此抛出FindException

        通过此方法创建的查找程序是惰性的,并不急切地检查给定的文件路径是目录还是打包模块。 因此,只有在调用这些方法导致搜索目录或打包模块并遇到错误时, findfindAll方法才会失败。

        参数
        entries - 模块目录或打包或分解模块路径的可能为空的路径数组
        结果
        ModuleFinder ,用于查找文件系统上的模块
      • compose

        static ModuleFinder compose​(ModuleFinder... finders)
        返回由零个或多个模块查找器序列组成的模块查找器。 生成的模块查找器的find方法将通过以数组索引顺序调用每个模块查找器的find方法来定位模块,直到找到模块或搜索了所有模块查找器。 生成的模块查找器的findAll方法将返回一组模块,其中包括第一个模块查找器定位的所有模块。 该组模块将包括由第二个或后续模块查找器定位的所有模块,这些模块未被序列中的先前模块查找器定位。

        当定位模块然后被抛出的异常或错误findfindAll底层模块发现者的方法将被传播到的所产生的模块取景器的呼叫者findfindAll方法。

        参数
        finders - 模块查找器阵列
        结果
        构成一系列模块查找器的 ModuleFinder