Summary

The specification of java.lang.Readable::read is insufficiently precise about the method's behavior when its specified java.nio.CharBuffer parameter has no elements remaining or is both read-only and empty.

Problem

It is not entirely clear from the specification that Readable::read returns zero when its parameter has been exhausted, or that it throws a java.nio.ReadOnlyBufferException when the parameter is both empty and read-only.

Solution

Update the specification to clarify the behavior.

Specification

--- a/src/java.base/share/classes/java/io/Reader.java
+++ b/src/java.base/share/classes/java/io/Reader.java
@@ -189,14 +189,18 @@ protected Reader(Object lock) {
      * Attempts to read characters into the specified character buffer.
      * The buffer is used as a repository of characters as-is: the only
      * changes made are the results of a put operation. No flipping or
-     * rewinding of the buffer is performed.
+     * rewinding of the buffer is performed. If the {@linkplain
+     * java.nio.CharBuffer#length length} of the specified character
+     * buffer is zero, then no characters will be read and zero will be
+     * returned.
      *
      * @param target the buffer to read characters into
-     * @return The number of characters added to the buffer, or
-     *         -1 if this source of characters is at its end
+     * @return The number of characters added to the buffer,
+     *         possibly zero, or -1 if this source of characters is at its end
      * @throws IOException if an I/O error occurs
      * @throws NullPointerException if target is null
-     * @throws java.nio.ReadOnlyBufferException if target is a read only buffer
+     * @throws java.nio.ReadOnlyBufferException if target is a read only buffer,
+     *         even if its length is zero
      * @since 1.5
      */
     public int read(CharBuffer target) throws IOException {

--- a/src/java.base/share/classes/java/lang/Readable.java
+++ b/src/java.base/share/classes/java/lang/Readable.java
@@ -40,14 +40,18 @@ public interface Readable {
      * Attempts to read characters into the specified character buffer.
      * The buffer is used as a repository of characters as-is: the only
      * changes made are the results of a put operation. No flipping or
-     * rewinding of the buffer is performed.
+     * rewinding of the buffer is performed. If the {@linkplain
+     * java.nio.CharBuffer#length length} of the specified character
+     * buffer is zero, then no characters will be read and zero will be
+     * returned.
      *
      * @param cb the buffer to read characters into
      * @return The number of {@code char} values added to the buffer,
-     *                 or -1 if this source of characters is at its end
+     *         possibly zero, or -1 if this source of characters is at its end
      * @throws IOException if an I/O error occurs
      * @throws NullPointerException if cb is null
-     * @throws java.nio.ReadOnlyBufferException if cb is a read only buffer
+     * @throws java.nio.ReadOnlyBufferException if cb is a read only buffer,
+     *         even if its length is zero
      */
     public int read(java.nio.CharBuffer cb) throws IOException;
 }

--- a/src/java.base/share/classes/java/nio/X-Buffer.java.template
+++ b/src/java.base/share/classes/java/nio/X-Buffer.java.template
@@ -471,13 +471,16 @@ public abstract sealed class $Type$Buffer
      * Attempts to read characters into the specified character buffer.
      * The buffer is used as a repository of characters as-is: the only
      * changes made are the results of a put operation. No flipping or
-     * rewinding of the buffer is performed.
+     * rewinding of the buffer is performed. If the {@linkplain #length
+     * length} of the specified character buffer is zero, then no characters
+     * will be read and zero will be returned.
      *
      * @param target the buffer to read characters into
-     * @return The number of characters added to the buffer, or
-     *         -1 if this source of characters is at its end
+     * @return The number of characters added to the buffer,
+     *         possibly zero, or -1 if this source of characters is at its end
      * @throws IOException if an I/O error occurs
-     * @throws ReadOnlyBufferException if target is a read only buffer
+     * @throws ReadOnlyBufferException if target is a read only buffer,
+     *         even if its length is zero
      * @since 1.5
      */
     public int read(CharBuffer target) throws IOException {