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 amodule 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 eachmodule. A module reader is also intended to be used byClassLoaderimplementations 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 mayhave a resource "java/lang/Object.class" that, by convention, is theclass file forjava.lang.Object. A module reader may treatdirectories in the module content as resources (whether it does or not ismodule reader specific). Where the module content contains a directorythat can be located as a resource then its name ends with a slash ('/'). Thedirectory can also be located with a name that drops the trailing slash.

AModuleReader isopen uponcreation and is closed by invoking theclose method. Failureto close a module reader may result in a resource leak. Thetry-with-resources statement provides a useful construct to ensure thatmodule readers are closed.

Implementation Requirements:
Implementations ofModuleReader should take great carewhen translating an abstract resource name to the location of a resource ina packaged module or on the file system. Implementations are advised totreat resource names with elements such as '., '..',elements containing file separators, or empty elements as "not found". Moregenerally, if the resource name is not in the stream of elements that thelist method returns then the resource should be treated as "notfound" to avoid inconsistencies.
Since:
9
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Closes the module reader.
    find(String name)
    Finds a resource, returning a URI to the resource in the module.
    Lists the contents of the module, returning a stream of elements thatare the names of all resources in the module.
    open(String name)
    Opens a resource, returning an input stream to read the resource inthe module.
    read(String name)
    Reads a resource, returning a byte buffer with the contents of theresource.
    default void
    Releases a byte buffer.

  • Method Details

    • 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 directorythen 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
      See Also:

    • open

      default Optional<InputStream> open(String name) throwsIOException
      Opens a resource, returning an input stream to read the resource inthe module.

      The behavior of the input stream when used after the module readeris 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 attemptsto construct aURL and open a connection to theresource.
      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

    • read

      default Optional<ByteBuffer> read(String name) throwsIOException
      Reads a resource, returning a byte buffer with the contents of theresource.The element at the returned buffer's position is the first byte of theresource, the element at the buffer's limit is the last byte of theresource. Once consumed, therelease methodmust be invoked. Failure to invoke therelease method may resultin a resource leak.
      API Note:
      This method is intended for high-performance class loading. Itis not capable (or intended) to read arbitrary large resources thatcould potentially be 2GB or larger. The rationale for using this methodin conjunction with therelease method is to allow module readerimplementations manage buffers in an efficient manner.
      Implementation Requirements:
      The default implementation invokes theopen method and reads all bytes from the input stream into a bytebuffer.
      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
      OutOfMemoryError - If the resource is larger thanInteger.MAX_VALUE, the maximum capacity of a byte buffer
      See Also:

    • release

      default void release(ByteBuffer bb)
      Releases a byte buffer. This method should be invoked after consumingthe contents of the buffer returned by theread method.The behavior of this method when invoked to release a buffer that hasalready been released, or the behavior when invoked to release a bufferafter aModuleReader is closed is implementation specific andtherefore not specified.
      Implementation Requirements:
      The default implementation doesn't do anything except checkif 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 thatare the names of all resources in the module. Whether the stream ofelements includes names corresponding to directories in the module ismodule reader specific.

      In lazy implementations then anIOException may be thrownwhen using the stream to list the module contents. If this occurs thentheIOException will be wrapped in anUncheckedIOException and thrown from the method that caused theaccess to be attempted.

      The returned stream may contain references to one or more open directoriesin the module. The directories are closed by closing the stream.

      The behavior of the stream when used after the module reader isclosed is implementation specific and therefore not specified.

      API Note:
      This method should be used within a try-with-resources statement or similarcontrol structure to ensure that any open directories referenced by thestream are closed promptly after the stream's operations have completed.
      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

    • close

      void close() throwsIOException
      Closes the module reader. Once closed then subsequent calls to locate orread a resource will fail by throwingIOException.

      A module reader is not required to be asynchronously closeable. If athread 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