AutoCloseable
, Closeable
public interface ModuleReader extends Closeable
A module reader is intended for cases where access to the resources in a module is required, regardless of whether the module has been loaded. A framework that scans a collection of packaged modules on the file system, for example, may use a module reader to access a specific resource in each module. A module reader is also intended to be used by ClassLoader
implementations that load classes and resources from modules.
A resource in a module is identified by an abstract name that is a '/
'-separated path string. For example, module java.base
may have a resource "java/lang/Object.class
" that, by convention, is the class file for java.lang.Object
. A module reader may treat directories in the module content as resources (whether it does or not is module reader specific). Where the module content contains a directory that can be located as a resource then its name ends with a slash ('/'). The directory can also be located with a name that drops the trailing slash.
A ModuleReader
is open upon creation and is closed by invoking the close
method. Failure to close a module reader may result in a resource leak. The
try-with-resources
statement provides a useful construct to ensure that module readers are closed.
A ModuleReader
implementation may require permissions to access resources in the module. Consequently the find
, open
, read
, and list
methods may throw
SecurityException
if access is denied by the security manager.
ModuleReader
should take great care when translating an abstract resource name to the location of a resource in a packaged module or on the file system. Implementations are advised to treat resource names with elements such as '.
, '..
', elements containing file separators, or empty elements as "not found". More generally, if the resource name is not in the stream of elements that the list
method returns then the resource should be treated as "not found" to avoid inconsistencies.Modifier and Type | Method | Description |
---|---|---|
void |
close() |
Closes the module reader. |
Optional |
find |
Finds a resource, returning a URI to the resource in the module. |
Stream |
list() |
Lists the contents of the module, returning a stream of elements that are the names of all resources in the module. |
default Optional |
open |
Opens a resource, returning an input stream to read the resource in the module. |
default Optional |
read |
Reads a resource, returning a byte buffer with the contents of the resource. |
default void |
release |
Releases a byte buffer. |
Optional<URI> find(String name) throws IOException
If the module reader can determine that the name locates a directory then the resulting URI will end with a slash ('/').
name
- The name of the resource to open for readingOptional
if the resource is not found or a URI cannot be constructed to locate the resourceIOException
- If an I/O error occurs or the module reader is closedSecurityException
- If denied by the security managerdefault Optional<InputStream> open(String name) throws IOException
The behavior of the input stream when used after the module reader is closed is implementation specific and therefore not specified.
find
method to get a URI to the resource. If found, then it attempts to construct a URL
and open a connection to the resource.name
- The name of the resource to open for readingOptional
if not foundIOException
- If an I/O error occurs or the module reader is closedSecurityException
- If denied by the security managerdefault Optional<ByteBuffer> read(String name) throws IOException
release
method must be invoked. Failure to invoke the release
method may result in a resource leak.release
method is to allow module reader implementations manage buffers in an efficient manner.open
method and reads all bytes from the input stream into a byte buffer.name
- The name of the resource to readOptional
if not foundIOException
- If an I/O error occurs or the module reader is closedSecurityException
- If denied by the security managerOutOfMemoryError
- If the resource is larger than Integer.MAX_VALUE
, the maximum capacity of a byte bufferdefault void release(ByteBuffer bb)
read
method. The behavior of this method when invoked to release a buffer that has already been released, or the behavior when invoked to release a buffer after a ModuleReader
is closed is implementation specific and therefore not specified.bb
- The byte buffer to releaseStream<String> list() throws IOException
In lazy implementations then an IOException
may be thrown when using the stream to list the module contents. If this occurs then the IOException
will be wrapped in an UncheckedIOException
and thrown from the method that caused the access to be attempted. SecurityException
may also be thrown when using the stream to list the module contents and access is denied by the security manager.
The returned stream may contain references to one or more open directories in the module. The directories are closed by closing the stream.
The behavior of the stream when used after the module reader is closed is implementation specific and therefore not specified.
IOException
- If an I/O error occurs or the module reader is closedSecurityException
- If denied by the security managervoid close() throws IOException
IOException
. A module reader is not required to be asynchronously closeable. If a thread is reading a resource and another thread invokes the close method, then the second thread may block until the read operation is complete.
close
in interface AutoCloseable
close
in interface Closeable
IOException
- if an I/O error occurs
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/module/ModuleReader.html