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

*** 43,53 ****
   * 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 {@code ClassLoader}
   * implementations that load classes and resources from modules. </p>
   *
!  * <p> A resource in a module is identified by a 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>
   *
   * <p> A {@code ModuleReader} is {@linkplain ModuleReference#open open} upon
--- 43,53 ----
   * 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 {@code ClassLoader}
   * 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>
   *
   * <p> A {@code ModuleReader} is {@linkplain ModuleReference#open open} upon
*** 59,70 ****
--- 59,80 ----
   * <p> A {@code ModuleReader} implementation may require permissions to access
   * resources in the module. Consequently the {@link #find find}, {@link #open
   * open}, {@link #read read}, and {@link #list list} methods may throw {@code
   * SecurityException} if access is denied by the security manager. </p>
   *
+  * @implSpec Implementations of {@code ModuleReader} should take great care
+  * when translating an abstract resource name to the location of a resource in
+  * a packaged module or on the file system. Implementations are advised to
+  * treat resource names with elements such as '{@code .},  '{@code ..}',
+  * elements containing file separators, or empty elements as "not found". More
+  * generally, if the resource name is not in the stream of elements that the
+  * {@code list} method returns then the resource should be treated as "not
+  * found" to avoid inconsistencies.
+  *
   * @see ModuleReference
   * @since 9
+  * @spec JPMS
   */
  
  public interface ModuleReader extends Closeable {
  
      /**
*** 146,155 ****
--- 156,168 ----
       *
       * @throws IOException
       *         If an I/O error occurs or the module reader is closed
       * @throws SecurityException
       *         If denied by the security manager
+      * @throws OutOfMemoryError
+      *         If the resource is larger than {@code Integer.MAX_VALUE},
+      *         the maximum capacity of a byte buffer
       *
       * @see ClassLoader#defineClass(String, ByteBuffer, java.security.ProtectionDomain)
       */
      default Optional<ByteBuffer> read(String name) throws IOException {
          Optional<InputStream> oin = open(name);