Module java.base
Package java.lang.module

## Interface ModuleReader

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`

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`void` `close()` Closes the module reader.
`Optional<URI>` `find(String name)` Finds a resource, returning a URI to the resource in the module.
`default Optional<InputStream>` `open(String name)` Opens a resource, returning an input stream to read the resource in the module.
`default Optional<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)
                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)`

#### 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

#### 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)`

#### 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 does nothing.
Parameters:
  `bb` - The byte buffer to release

#### 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 `InputStream`s 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