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

Interface ModuleReader

  • All Superinterfaces:
    AutoCloseableCloseable

    public interface ModuleReader
    extends Closeable
    提供对模块内容的访问。

    模块阅读器适用于需要访问模块中资源的情况,无论模块是否已加载。 例如,扫描文件系统上的打包模块集合的框架可以使用模块读取器来访问每个模块中的特定资源。 模块阅读器也可用于从模块加载类和资源的ClassLoader实现。

    模块中的资源由抽象名称标识,该名称是“ //的路径字符串。 例如,模块java.base可以具有资源“ java/lang/Object.class ”,按照惯例,该资源是java.lang.Object的类文件。 模块读取器可以将模块内容中的目录视为资源(无论它是否是模块读取器特定的)。 如果模块内容包含可以作为资源定位的目录,则其名称以斜杠('/')结尾。 也可以使用删除尾部斜杠的名称来定位目录。

    A ModuleReader在创建时为open ,并通过调用close方法关闭。 未能关闭模块阅读器可能会导致资源泄漏。 try-with-resources语句提供了一个有用的构造,以确保关闭模块读取器。

    ModuleReader实现可能需要权限才能访问模块中的资源。 因此,该findopenreadlist方法可能抛出SecurityException如果访问由安全管理器拒绝。

    实现要求:
    将抽象资源名称转换为打包模块或文件系统中资源的位置时,应特别注意ModuleReader实现。 建议实现使用诸如“ . ,“ .. ”之类的元素,包含文件分隔符的元素或“未找到”的空元素来处理资源名称。 更一般地,如果资源名称不在list方法返回的元素流中, list将资源视为“未找到”以避免不一致。
    从以下版本开始:
    9
    另请参见:
    ModuleReference
    • 方法详细信息

      • find

        Optional<URI> find​(String name)
                    throws IOException
        查找资源,将URI返回给模块中的资源。

        如果模块阅读器可以确定名称找到目录,那么结果URI将以斜杠('/')结尾。

        参数
        name - 要打开以供阅读的资源的名称
        结果
        资源的URI; 如果找不到资源或者无法构造URI来定位资源,则为空Optional
        异常
        IOException - 如果发生I / O错误或模块阅读器已关闭
        SecurityException - 如果安全经理拒绝
        另请参见:
        ClassLoader.getResource(String)
      • open

        default Optional<InputStream> open​(String name)
                                    throws IOException
        打开资源,返回输入流以读取模块中的资源。

        在模块读取器关闭后使用时输入流的行为是特定于实现的,因此未指定。

        实现要求:
        默认实现调用find方法来获取资源的URI。 如果找到,则它尝试构造URL并打开与资源的连接。
        参数
        name - 要打开以供阅读的资源的名称
        结果
        读取资源的输入流,如果未找到 OptionalOptional
        异常
        IOException - 如果发生I / O错误或模块阅读器已关闭
        SecurityException - 如果安全管理员拒绝
      • read

        default Optional<ByteBuffer> read​(String name)
                                   throws IOException
        读取资源,返回包含资源内容的字节缓冲区。 返回缓冲区位置的元素是资源的第一个字节,缓冲区限制的元素是资源的最后一个字节。 消费后,必须调用release方法。 无法调用release方法可能会导致资源泄漏。
        API Note:
        此方法适用于高性能类加载。 它无法(或打算)读取可能为2GB或更大的任意大型资源。 将此方法与release方法结合使用的release原理是允许模块读取器实现以有效的方式管理缓冲区。
        实现要求:
        默认实现调用 open方法,并将输入流中的所有字节读入字节缓冲区。
        参数
        name - 要读取的资源的名称
        结果
        包含资源内容的字节缓冲区,如果未找到 OptionalOptional
        异常
        IOException - 如果发生I / O错误或模块阅读器已关闭
        SecurityException - 如果安全经理拒绝
        OutOfMemoryError - 如果资源大于 Integer.MAX_VALUEInteger.MAX_VALUE字节缓冲区的最大容量
        另请参见:
        ClassLoader.defineClass(String, ByteBuffer, java.security.ProtectionDomain)
      • release

        default void release​(ByteBuffer bb)
        释放一个字节缓冲区。 在使用read方法返回的缓冲区内容后,应调用此方法。 调用此方法以释放已释放的缓冲区时的行为,或者在关闭ModuleReader后调用以释放缓冲区时的行为是特定于实现的,因此未指定。
        实现要求:
        除了检查字节缓冲区是否为空之外,默认实现不执行任何操作。
        参数
        bb - 要释放的字节缓冲区
      • list

        Stream<String> list()
                     throws IOException
        列出模块的内容,返回元素流,这些元素是模块中所有资源的名称。 元素流是否包括与模块中的目录相对应的名称是模块读取器特定的。

        在延迟实现中,当使用流列出模块内容时,可能会抛出IOException 如果发生这种情况,则IOException将被包装在UncheckedIOException中,并从导致尝试访问的方法中抛出。 当使用流列出模块内容并且安全管理器拒绝访问时,也可能抛出SecurityException

        在关闭模块读取器之后使用流的行为是特定于实现的,因此未指定。

        结果
        元素流,它是模块中所有资源的名称
        异常
        IOException - 如果发生I / O错误或模块阅读器已关闭
        SecurityException - 如果安全经理拒绝
      • close

        void close()
            throws IOException
        关闭模块阅读器。 一旦关闭,随后的定位或读取资源的调用将失败,抛出IOException

        模块阅读器不需要是异步可关闭的。 如果线程正在读取资源而另一个线程调用close方法,则第二个线程可能会阻塞,直到读取操作完成。

        Specified by:
        close在界面 AutoCloseable
        Specified by:
        close ,界面 Closeable
        异常
        IOException - if an I/O error occurs