Package Summary Overview Summary

class:ModuleReader [CHANGED]

All Superinterfaces:

AutoCloseable, Closeable
```
public interface ModuleReader
extends Closeable
```
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 by ClassLoader implementations that load classes and resources from modules.

A Resource in a module is identified by a 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 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 readlist methods may throw SecurityException if access is denied by the security manager.

Since:

9

See Also:

ModuleReference

All Superinterfaces:

AutoCloseable, Closeable
```
public interface ModuleReader
extends Closeable
```
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 by ClassLoader implementations that load classes and resources from modules.

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 and read methods may throw SecurityException if access is denied by the security manager.

Since:

9

See Also:

ModuleReference

All Superinterfaces:

AutoCloseable, Closeable
```
public interface ModuleReader
extends Closeable
```
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 by ClassLoader implementations that load classes and resources from modules.

A Resource in a module is identified by a 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 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.

Since:

9

See Also:

ModuleReference

method:find(java.lang.String) [NONE]

find
```
Optional<URI> find(String name)
            throws IOException
```
Finds a resource, returning a URI to the resource in the module.

Parameters:

name - The name of the resource to open for reading

Returns:

A URI to the resource; an empty Optional 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)

method:open(java.lang.String) [CHANGED]

open
```
default Optional<InputStream> open(String name)
                            throws IOException
```
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 the 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.

Parameters:

name - The name of the resource to open for reading

Returns:

An input stream to read the resource or an empty Optional if not found

Throws:

IOException - If an I/O error occurs or the module reader is closed

SecurityException - If denied by the security manager

open
```
default Optional<InputStream> open(String name)
                            throws IOException
```
Opens a resource, returning an input stream to read the resource in the module.

Implementation Requirements:

The default implementation invokes the 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.

Parameters:

name - The name of the resource to open for reading

Returns:

An input stream to read the resource or an empty Optional if not found

Throws:

IOException - If an I/O error occurs or the module reader is closed

SecurityException - If denied by the security manager

open
```
default Optional<InputStream> open(String name)
                            throws IOException
```
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 the 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.

Parameters:

name - The name of the resource to open for reading

Returns:

An input stream to read the resource or an empty Optional if not found

Throws:

IOException - If an I/O error occurs or the module reader is closed

SecurityException - If denied by the security manager

method:read(java.lang.String) [NONE]

read
```
default Optional<ByteBuffer> read(String name)
                           throws IOException
```
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, the release method must be invoked. Failure to invoke the release 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 rational for using this method in conjunction with the release method is to allow module reader implementations manage buffers in an efficient manner.

Implementation Requirements:

The default implementation invokes the open 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 empty Optional if not found

Throws:

IOException - If an I/O error occurs or the module reader is closed

SecurityException - If denied by the security manager

See Also:

ClassLoader.defineClass(String, ByteBuffer, java.security.ProtectionDomain)

method:release(java.nio.ByteBuffer) [NONE]

release
```
default void release(ByteBuffer bb)
```
Release a byte buffer. This method should be invoked after consuming the contents of the buffer returned by the 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.

Implementation Requirements:

The default implementation doesn't do anything except check if the byte buffer is null.

Parameters:

bb - The byte buffer to release

method:list() [ADDED]

list
```
Stream<String> list()
             throws IOException
```
Lists the contents of the module, returning a stream of elements that are the names of all resources in the module.
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 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

method:close() [CHANGED]

close
```
void close()
    throws IOException
```
Closes the module reader. Once closed then subsequent calls to locate or read a resource will fail by returning Optional.empty() orthrowing 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. The behavior of InputStreams obtained using the open method and used after the module reader is closed is implementation specific and therefore not specified.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if an I/O error occurs

close
```
void close()
    throws IOException
```
Closes the module reader. Once closed then subsequent calls to locate or read a resource will fail by returning Optional.empty() or throwing 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.

The behavior of InputStreams obtained using the open method and used after the module reader is closed is implementation specific and therefore not specified.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if an I/O error occurs

close
```
void close()
    throws IOException
```
Closes the module reader. Once closed then subsequent calls to locate or read a resource will fail by throwing 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.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if an I/O error occurs