src/java.base/share/classes/java/io/ObjectInputStream.java

rev 14187 : 8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete
Summary: Clarify and expand specification of ObjectInputStream.read(byte[],int,int) and both variants of {DataInput,DataInputStream,ObjectInputStream,RandomAccessfile}.readFully().
Reviewed-by: XXX

@@ -851,14 +851,18 @@
      * Reads into an array of bytes.  This method will block until some input
      * is available. Consider using java.io.DataInputStream.readFully to read
      * exactly 'length' bytes.
      *
      * @param   buf the buffer into which the data is read
-     * @param   off the start offset of the data
+     * @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.
+     * @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
+     *          {@code buf.length - off}
      * @throws  IOException If an I/O error has occurred.
      * @see java.io.DataInputStream#readFully(byte[],int,int)
      */
     public int read(byte[] buf, int off, int len) throws IOException {
         if (buf == null) {

@@ -1012,10 +1016,11 @@
 
     /**
      * Reads bytes, blocking until all bytes are read.
      *
      * @param   buf the buffer into which the data is read
+     * @throws  NullPointerException If {@code buf} is {@code null}.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
     public void readFully(byte[] buf) throws IOException {
         bin.readFully(buf, 0, buf.length, false);

@@ -1023,12 +1028,16 @@
 
     /**
      * Reads bytes, blocking until all bytes are read.
      *
      * @param   buf the buffer into which the data is read
-     * @param   off the start offset of the data
+     * @param   off the start offset into the data array {@code buf}
      * @param   len the maximum number of bytes to read
+     * @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
+     *          {@code buf.length - off}
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
     public void readFully(byte[] buf, int off, int len) throws IOException {
         int endoff = off + len;