src/java.base/share/classes/java/lang/module/ModuleReader.java

@@ -46,11 +46,15 @@
  * implementations that load classes and resources from modules. </p>
  *
  * <p> A resource in a module is identified by an abstract name that is a
  * '{@code /}'-separated path string. For example, module {@code java.base} may
  * have a resource "{@code java/lang/Object.class}" that, by convention, is the
- * class file for {@code java.lang.Object}. </p>
+ * class file for {@code java.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. </p>
  *
  * <p> A {@code ModuleReader} is {@linkplain ModuleReference#open open} upon
  * creation and is closed by invoking the {@link #close close} method.  Failure
  * to close a module reader may result in a resource leak.  The {@code
  * try-with-resources} statement provides a useful construct to ensure that

@@ -78,10 +82,13 @@
 public interface ModuleReader extends Closeable {
 
     /**
      * Finds a resource, returning a URI to the resource in the module.
      *
+     * <p> If the module reader can determine that the name locates a directory
+     * then the resulting URI will end with a slash ('/'). </p>
+     *
      * @param  name
      *         The name of the resource to open for reading
      *
      * @return A URI to the resource; an empty {@code Optional} if the resource
      *         is not found or a URI cannot be constructed to locate the

@@ -138,11 +145,11 @@
      * must be invoked. Failure to invoke the {@code release} method may result
      * in a resource leak.
      *
      * @apiNote 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
+     * could potentially be 2GB or larger. The rationale for using this method
      * in conjunction with the {@code release} method is to allow module reader
      * implementations manage buffers in an efficient manner.
      *
      * @implSpec The default implementation invokes the {@link #open(String)
      * open} method and reads all bytes from the input stream into a byte

@@ -193,11 +200,13 @@
         Objects.requireNonNull(bb);
     }
 
     /**
      * Lists the contents of the module, returning a stream of elements that
-     * are the names of all resources in the module.
+     * 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