Movatterモバイル変換

Interface ModuleReader

All Superinterfaces:
AutoCloseable,Closeable
```
public interfaceModuleReaderextendsCloseable
```
Provides access to the content of a module.
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 byClassLoader 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, modulejava.base may have a resource "java/lang/Object.class" that, by convention, is the class file forjava.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.
AModuleReader isopen upon creation and is closed by invoking theclose 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.
AModuleReader implementation may require permissions to access resources in the module. Consequently thefind,open,read, andlist methods may throw SecurityException if access is denied by the security manager.
Implementation Requirements:
Implementations ofModuleReader 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 thelist method returns then the resource should be treated as "not found" to avoid inconsistencies.
Since:
9
See Also:
ModuleReference

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`void`	`close()`	Closes the module reader.
`Optional<URI>`	`find(String name)`	Finds a resource, returning a URI to the resource in the module.
`Stream<String>`	`list()`	Lists the contents of the module, returning a stream of elements that are the names of all resources in the module.
`defaultOptional<InputStream>`	`open(String name)`	Opens a resource, returning an input stream to read the resource in the module.
`defaultOptional<ByteBuffer>`	`read(String name)`	Reads a resource, returning a byte buffer with the contents of the resource.
`default void`	`release(ByteBuffer bb)`	Release a byte buffer.

- Method Detail
  - find
```
Optional<URI> find(String name)            throwsIOException
```
    Finds a resource, returning a URI to the resource in the module.
    If the module reader can determine that the name locates a directory then the resulting URI will end with a slash ('/').
    Parameters:
    name - The name of the resource to open for reading
    Returns:
    A URI to the resource; an emptyOptional if the resource is not found or a URI cannot be constructed to locate the resource
    Throws:
    IOException - If an I/O error occurs or the module reader is closed
    SecurityException - If denied by the security manager
    See Also:
    ClassLoader.getResource(String)
  - open
```
default Optional<InputStream> open(String name)                            throwsIOException
```
    Opens a resource, returning an input stream to read the resource in the module.
    The behavior of the input stream when used after the module reader is closed is implementation specific and therefore not specified.
    Implementation Requirements:
    The default implementation invokes thefind method to get a URI to the resource. If found, then it attempts to construct aURL and open a connection to the resource.
    Parameters:
    name - The name of the resource to open for reading
    Returns:
    An input stream to read the resource or an emptyOptional if not found
    Throws:
    IOException - If an I/O error occurs or the module reader is closed
    SecurityException - If denied by the security manager
  - read
```
default Optional<ByteBuffer> read(String name)                           throwsIOException
```
    Reads a resource, returning a byte buffer with the contents of the resource. The element at the returned buffer's position is the first byte of the resource, the element at the buffer's limit is the last byte of the resource. Once consumed, therelease method must be invoked. Failure to invoke therelease method may result in a resource leak.
    API Note:
    This method is intended for high-performance class loading. It is not capable (or intended) to read arbitrary large resources that could potentially be 2GB or larger. The rationale for using this method in conjunction with therelease method is to allow module reader implementations manage buffers in an efficient manner.
    Implementation Requirements:
    The default implementation invokes theopen method and reads all bytes from the input stream into a byte buffer.
    Parameters:
    name - The name of the resource to read
    Returns:
    A byte buffer containing the contents of the resource or an emptyOptional if not found
    Throws:
    IOException - If an I/O error occurs or the module reader is closed
    SecurityException - If denied by the security manager
    OutOfMemoryError - If the resource is larger thanInteger.MAX_VALUE, the maximum capacity of a byte buffer
    See Also:
    ClassLoader.defineClass(String, ByteBuffer, java.security.ProtectionDomain)
  - release
```
default void release(ByteBuffer bb)
```
    Release a byte buffer. This method should be invoked after consuming the contents of the buffer returned by theread 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 aModuleReader is closed is implementation specific and therefore not specified.
    Implementation Requirements:
    The default implementation doesn't do anything except check if the byte buffer is null.
    Parameters:
    bb - The byte buffer to release
  - list
```
Stream<String> list()             throwsIOException
```
    Lists the contents of the module, returning a stream of elements that are the names of all resources in the module. Whether the stream of elements includes names corresponding to directories in the module is module reader specific.
    In lazy implementations then anIOException may be thrown when using the stream to list the module contents. If this occurs then theIOException will be wrapped in anUncheckedIOException 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 behavior of the stream when used after the module reader is closed is implementation specific and therefore not specified.
    Returns:
    A stream of elements that are the names of all resources in the module
    Throws:
    IOException - If an I/O error occurs or the module reader is closed
    SecurityException - If denied by the security manager
  - close
```
void close()    throwsIOException
```
    Closes the module reader. Once closed then subsequent calls to locate or read a resource will fail by throwingIOException.
    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.
    Specified by:
    close in interface AutoCloseable
    Specified by:
    close in interface Closeable
    Throws:
    IOException - if an I/O error occurs

Movatterモバイル変換

Interface ModuleReader

Method Summary

Method Detail

find

open

read

release

list

close