Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8284022

java.io bulk read(...) end-of-stream return value descriptions ambiguous

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 19
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Verbiage is changed for clarity and matches existing behavior so no risk.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Modify the descriptions of the return value for some bulk read (read(byte[],int,int)) methods in java.io to be consistent and more accurate.

      Problem

      The descriptions of the return value for some bulk read (read(byte[],int,int)) methods in java.io are inconsistent and ambiguous.

      Solution

      Change the problematic verbiage to:

      the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

      Specification

      --- a/src/java.base/share/classes/java/io/ObjectInput.java
      +++ b/src/java.base/share/classes/java/io/ObjectInput.java
      @@ -62,8 +62,9 @@ public interface ObjectInput extends DataInput, AutoCloseable {
            * Reads into an array of bytes.  This method will
            * block until some input is available.
            * @param   b the buffer into which the data is read
      -     * @return  the actual number of bytes read, -1 is
      -     *          returned when the end of the stream is reached.
      +     * @return  the total number of bytes read into the buffer, or
      +     *          {@code -1} if there is no more data because the end of
      +     *          the stream has been reached.
            * @throws  IOException If an I/O error has occurred.
            */
           public int read(byte[] b) throws IOException;
      @@ -74,8 +75,9 @@ public interface ObjectInput extends DataInput, AutoCloseable {
            * @param   b the buffer into which the data is read
            * @param   off the start offset of the data
            * @param   len the maximum number of bytes read
      -     * @return  the actual number of bytes read, -1 is
      -     *          returned when the end of the stream is reached.
      +     * @return  the total number of bytes read into the buffer, or
      +     *          {@code -1} if there is no more data because the end of
      +     *          the stream has been reached.
            * @throws  IOException If an I/O error has occurred.
            */
           public int read(byte[] b, int off, int len) throws IOException;
      diff --git a/src/java.base/share/classes/java/io/ObjectInputStream.java b/src/java.base/share/classes/java/io/ObjectInputStream.java
      index 14812fea9ad..319981e864b 100644
      --- a/src/java.base/share/classes/java/io/ObjectInputStream.java
      +++ b/src/java.base/share/classes/java/io/ObjectInputStream.java
      @@ -1031,8 +1031,9 @@ public class ObjectInputStream
            * @param   buf the buffer into which the data is read
            * @param   off the start offset in the destination array {@code buf}
            * @param   len the maximum number of bytes read
      -     * @return  the actual number of bytes read, -1 is returned when the end of
      -     *          the stream is reached.
      +     * @return  the total number of bytes read into the buffer, or
      +     *          {@code -1} if there is no more data because the end of
      +     *          the stream has been reached.
            * @throws  NullPointerException if {@code buf} is {@code null}.
            * @throws  IndexOutOfBoundsException if {@code off} is negative,
            *          {@code len} is negative, or {@code len} is greater than
      diff --git a/src/java.base/share/classes/java/io/SequenceInputStream.java b/src/java.base/share/classes/java/io/SequenceInputStream.java
      index 5f692ce6c44..95d489e7d54 100644
      --- a/src/java.base/share/classes/java/io/SequenceInputStream.java
      +++ b/src/java.base/share/classes/java/io/SequenceInputStream.java
      @@ -177,7 +177,9 @@ public class SequenceInputStream extends InputStream {
            * @param      off   the start offset in array {@code b}
            *                   at which the data is written.
            * @param      len   the maximum number of bytes read.
      -     * @return     int   the number of bytes read.
      +     * @return     the total number of bytes read into the buffer, or
      +     *             {@code -1} if there is no more data because the end of
      +     *             the last contained stream has been reached.
            * @throws     NullPointerException If {@code b} is {@code null}.
            * @throws     IndexOutOfBoundsException If {@code off} is negative,
            *             {@code len} is negative, or {@code len} is

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              bpb Brian Burkhalter
              Reporter:
              rmandalasunw Ranjith Mandala (Inactive)
              Reviewed By:
              Lance Andersen
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: