模块 java.base
包 java.lang.module

接口 ModuleReader

所有父级接口：
AutoCloseable , Closeable
public interface ModuleReader extends Closeable
提供对模块内容的访问。

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

模块中的资源由抽象名称标识，该抽象名称是“/”分隔的路径字符串。例如，模块 java.base 可能有一个资源“java/lang/Object.class”，按照惯例，它是 java.lang.Object 的类文件。模块阅读器可以将模块内容中的目录视为资源（是否这样做是特定于模块阅读器的）。如果模块内容包含一个可以作为资源定位的目录，那么它的名称以斜杠 ('/') 结尾。该目录也可以使用去掉尾部斜杠的名称来定位。

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

ModuleReader 实现可能需要访问模块中资源的权限。因此，如果安全管理器拒绝访问，find 、open 、read 和 list 方法可能会抛出 SecurityException。

实现要求：
ModuleReader 的实现在将抽象资源名称转换为打包模块或文件系统中的资源位置时应格外小心。建议实施将资源名称与元素（例如“.”、“..”）、包含文件分隔符的元素或空元素视为“未找到”。更一般地说，如果资源名称不在 list 方法返回的元素流中，则应将资源视为“未找到”以避免不一致。
自从：
9
参见：

  • 方法总结

    修饰符和类型
    方法
    描述
    void
    close()
    关闭模块阅读器。
    Optional<URI>
    find(String name)
    查找资源，将 URI 返回到模块中的资源。
    Stream<String>
    list()
    列出模块的内容，返回一个元素流，这些元素是模块中所有资源的名称。
    default Optional<InputStream>
    open(String name)
    打开资源，返回输入流以读取模块中的资源。
    default Optional<ByteBuffer>
    read(String name)
    读取资源，返回包含资源内容的字节缓冲区。
    default void
    release(ByteBuffer bb)
    释放字节缓冲区。

  • 方法详情

    • find

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

      如果模块阅读器可以确定该名称位于一个目录，那么生成的 URI 将以斜杠 ('/') 结尾。

      参数：
      name - 为阅读而打开的资源名称
      返回：
      资源的 URI；一个空的 Optional 如果找不到资源或无法构造 URI 来定位资源
      抛出：
      IOException - 如果发生 I/O 错误或模块读取器关闭
      SecurityException - 如果安全经理拒绝
      参见：

    • open

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

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

      实现要求：
      默认实现调用 find 方法来获取资源的 URI。如果找到，则它会尝试构造一个 URL 并打开到该资源的连接。
      参数：
      name - 为阅读而打开的资源名称
      返回：
      用于读取资源的输入流或空的 Optional（如果未找到）
      抛出：
      IOException - 如果发生 I/O 错误或模块读取器关闭
      SecurityException - 如果安全经理拒绝

    • read

      default Optional <ByteBuffer > read(String  name) throws IOException
      读取资源，返回包含资源内容的字节缓冲区。返回缓冲区位置的元素是资源的第一个字节，缓冲区边界处的元素是资源的最后一个字节。消费后，必须调用 release 方法。未能调用 release 方法可能会导致资源泄漏。
      API 注意：
      此方法用于高性能类加载。它无法（或无意）读取可能为 2GB 或更大的任意大型资源。将此方法与 release 方法结合使用的基本原理是允许模块读取器实现以有效的方式管理缓冲区。
      实现要求：
      默认实现调用 open 方法并将输入流中的所有字节读入字节缓冲区。
      参数：
      name - 要读取的资源的名称
      返回：
      包含资源内容的字节缓冲区，如果未找到则为空 Optional
      抛出：
      IOException - 如果发生 I/O 错误或模块读取器关闭
      SecurityException - 如果安全经理拒绝
      OutOfMemoryError - 如果资源大于 Integer.MAX_VALUE ，一个字节缓冲区的最大容量
      参见：

    • release

      default void release(ByteBuffer  bb)
      释放字节缓冲区。应在使用 read 方法返回的缓冲区内容后调用此方法。调用此方法以释放已释放的缓冲区时的行为，或在ModuleReader 关闭后调用以释放缓冲区时的行为是特定于实现的，因此未指定。
      实现要求：
      默认实现除了检查字节缓冲区是否为空外什么都不做。
      参数：
      bb - 要释放的字节缓冲区

    • list

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

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

      返回的流可能包含对模块中一个或多个打开目录的引用。通过关闭流关闭目录。

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

      API 注意：
      此方法应在 try-with-resources 语句或类似的控制结构中使用，以确保在流的操作完成后立即关闭流引用的任何打开的目录。
      返回：
      元素流，是模块中所有资源的名称
      抛出：
      IOException - 如果发生 I/O 错误或模块读取器关闭
      SecurityException - 如果安全经理拒绝

    • close

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

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

      指定者：
      close 在接口 AutoCloseable 中
      指定者：
      close 在接口 Closeable 中
      抛出：
      IOException - 如果发生 I/O 错误