-
- All Superinterfaces:
-
AutoCloseable
,Closeable
public interface ModuleReader extends Closeable
提供对模块内容的访问。模块阅读器适用于需要访问模块中资源的情况,无论模块是否已加载。 例如,扫描文件系统上的打包模块集合的框架可以使用模块读取器来访问每个模块中的特定资源。 模块阅读器也可用于从模块加载类和资源的
ClassLoader
实现。模块中的资源由抽象名称标识,该名称是“
/
”/
的路径字符串。 例如,模块java.base
可以具有资源“java/lang/Object.class
”,按照惯例,该资源是java.lang.Object
的类文件。 模块读取器可以将模块内容中的目录视为资源(无论它是否是模块读取器特定的)。 如果模块内容包含可以作为资源定位的目录,则其名称以斜杠('/')结尾。 也可以使用删除尾部斜杠的名称来定位目录。A
ModuleReader
在创建时为open ,并通过调用close
方法关闭。 未能关闭模块阅读器可能会导致资源泄漏。try-with-resources
语句提供了一个有用的构造,以确保关闭模块读取器。ModuleReader
实现可能需要权限才能访问模块中的资源。 因此,该find
,open
,read
和list
方法可能抛出SecurityException
如果访问由安全管理器拒绝。- 实现要求:
-
将抽象资源名称转换为打包模块或文件系统中资源的位置时,应特别注意
ModuleReader
实现。 建议实现使用诸如“.
,“..
”之类的元素,包含文件分隔符的元素或“未找到”的空元素来处理资源名称。 更一般地,如果资源名称不在list
方法返回的元素流中,list
将资源视为“未找到”以避免不一致。 - 从以下版本开始:
- 9
- 另请参见:
-
ModuleReference
-
-
方法摘要
所有方法 实例方法 抽象方法 Default Methods 变量和类型 方法 描述 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;
如果找不到资源或者无法构造URI来定位资源,则为空
Optional
- 异常
-
IOException
- 如果发生I / O错误或模块阅读器已关闭 -
SecurityException
- 如果安全经理拒绝 - 另请参见:
-
ClassLoader.getResource(String)
-
open
default Optional<InputStream> open(String name) throws IOException
打开资源,返回输入流以读取模块中的资源。在模块读取器关闭后使用时输入流的行为是特定于实现的,因此未指定。
- 实现要求:
-
默认实现调用
find
方法来获取资源的URI。 如果找到,则它尝试构造URL
并打开与资源的连接。 - 参数
-
name
- 要打开以供阅读的资源的名称 - 结果
-
读取资源的输入流,如果未找到
Optional
空Optional
- 异常
-
IOException
- 如果发生I / O错误或模块阅读器已关闭 -
SecurityException
- 如果安全管理员拒绝
-
read
default Optional<ByteBuffer> read(String name) throws IOException
读取资源,返回包含资源内容的字节缓冲区。 返回缓冲区位置的元素是资源的第一个字节,缓冲区限制的元素是资源的最后一个字节。 消费后,必须调用release
方法。 无法调用release
方法可能会导致资源泄漏。- API Note:
-
此方法适用于高性能类加载。
它无法(或打算)读取可能为2GB或更大的任意大型资源。
将此方法与
release
方法结合使用的release
原理是允许模块读取器实现以有效的方式管理缓冲区。 - 实现要求:
-
默认实现调用
open
方法,并将输入流中的所有字节读入字节缓冲区。 - 参数
-
name
- 要读取的资源的名称 - 结果
-
包含资源内容的字节缓冲区,如果未找到
Optional
空Optional
- 异常
-
IOException
- 如果发生I / O错误或模块阅读器已关闭 -
SecurityException
- 如果安全经理拒绝 -
OutOfMemoryError
- 如果资源大于Integer.MAX_VALUE
,Integer.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
-
-