8222329: Readable read(CharBuffer) does not specify that 0 is returned when there is no remaining space in buffer

Reviewed-by: rriggs, lancea, alanb

Author: Brian Burkhalter

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 {

src/java.base/share/classes/java/lang/Readable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -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;
 }

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 {