Summary

Clarify that the stream returned from ModuleReader::list may contain references to open directories in the module, and should therefore be closed.

Problem

ModuleReader facilitates access to a module's content, which may be inside the Java run-time system or in an artifact such as a modular JAR file. The list method lists the contents of the module, returning a stream of elements that are the names of all resources in the module.

The intention of the list method is to allow for "lazy" streams. In this context, a lazy stream over the contents may hold references to resources that should be released, e.g. references to open directories in the module.

Solution

Update the specification of ModuleReader::list to:

1. Clarify that the returned stream may contain references to open directories in the module, and should therefore be closed.

2. Add an API note suggesting to use a try-with-resources construct or similar.

The addition of a normative statement and an API note is similar to how such streams are handled elsewhere, e.g. java.nio.file.Files::list.

Specification

Add the following paragraph and apiNote to java.lang.module.ModuleReader::list:

  /**
    * 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.
    *
    * <p> In lazy implementations then an {@code IOException} may be thrown
    * when using the stream to list the module contents. If this occurs then
    * the {@code IOException} will be wrapped in an {@link
    * java.io.UncheckedIOException} and thrown from the method that caused the
    * access to be attempted. {@code SecurityException} may also be thrown
    * when using the stream to list the module contents and access is denied
    * by the security manager. </p>
    *
+   * <p> The returned stream may contain references to one or more open directories
+   * in the module. The directories are closed by closing the stream. </p>
+   *
    * <p> The behavior of the stream when used after the module reader is
    * closed is implementation specific and therefore not specified. </p>
    *
+   * @apiNote
+   * This method should be used within a try-with-resources statement or similar
+   * control structure to ensure that any open directories referenced by the
+   * stream are closed promptly after the stream's operations have completed.
    *
    * @return 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
    * @throws SecurityException
    *         If denied by the security manager
    */
   Stream<String> list() throws IOException;