Module java.base
Package java.lang.module

Interface ModuleReader

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

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

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

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

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

实现要求:
ModuleReader的实现在将抽象资源名称转换为打包模块或文件系统上资源位置时应当非常小心。建议实现将包含诸如“.”、“..”、包含文件分隔符的元素或空元素的资源名称视为“未找到”。更一般地，如果资源名称不在list方法返回的元素流中，则应将资源视为“未找到”，以避免不一致性。
自 JDK 版本:
9
参见:

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    释放字节缓冲区。

  • Method Details

    • find

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

      如果模块阅读器可以确定名称定位到一个目录，则生成的 URI 将以斜杠（'/'）结尾。

      参数:
      name - 要打开以进行读取的资源的名称
      返回:
      一个指向资源的 URI；如果未找到资源或无法构造 URI 来定位资源，则为空的Optional
      抛出:
      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后调用释放缓冲区时，此方法的行为是实现特定的，因此未指定。
      实现要求:
      默认实现仅检查字节缓冲区是否为 null。
      参数:
      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 在接口 AutoCloseable中
      指定者:
      close 在接口 Closeable中
      抛出:
      IOException - 如果发生 I/O 错误