Summary

Add an API note to java.io.ByteInputStream.read(byte[],int,int) to highlight that it returns -1 and not 0 at end of stream if the len parameter is zero.

Problem

The superclass java.io.InputStream specifies that read(byte[],int,int) returns zero if the third parameter, the number of bytes to read, is zero. For this scenarior when a ByteArrayInputStream is at end of stream, the value -1 is returned.

Solution

Add an API note to java.io.ByteInputStream.read(byte[],int,int) highlighting the difference with respect to its parent class.

Specification

@@ -145,28 +145,32 @@ public class ByteArrayInputStream extends InputStream {
     public synchronized int read() {
         return (pos < count) ? (buf[pos++] & 0xff) : -1;
     }

     /**
      * Reads up to {@code len} bytes of data into an array of bytes from this
      * input stream.  If {@code pos} equals {@code count}, then {@code -1} is
      * returned to indicate end of file.  Otherwise, the  number {@code k} of
      * bytes read is equal to the smaller of {@code len} and {@code count-pos}.
      * If {@code k} is positive, then bytes {@code buf[pos]} through
      * {@code buf[pos+k-1]} are copied into {@code b[off]} through
      * {@code b[off+k-1]} in the manner performed by {@code System.arraycopy}.
      * The value {@code k} is added into {@code pos} and {@code k} is returned.
      * <p>
+     * Unlike the {@link InputStream#read(byte[],int,int) overridden method}
+     * of {@code InputStream}, this method returns {@code -1} instead of zero
+     * if the end of the stream has been reached and {@code len == 0}.
+     * <p>
      * This {@code read} method cannot block.
      *
      * @param   b     the buffer into which the data is read.
      * @param   off   the start offset in the destination array {@code b}
      * @param   len   the maximum 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 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 greater than
      * {@code b.length - off}
      */
     public synchronized int read(byte b[], int off, int len) {