src/java.base/share/classes/java/io/DataInputStream.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

*** 1,7 ****
  /*
!  * Copyright (c) 1994, 2006, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * Copyright (c) 1994, 2016, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 148,187 ****
      public final int read(byte b[], int off, int len) throws IOException {
          return in.read(b, off, len);
      }
  
      /**
!      * See the general contract of the <code>readFully</code>
!      * method of <code>DataInput</code>.
       * <p>
       * Bytes
       * for this operation are read from the contained
       * input stream.
       *
       * @param      b   the buffer into which the data is read.
!      * @exception  EOFException  if this input stream reaches the end before
       *             reading all the bytes.
!      * @exception  IOException   the stream has been closed and the contained
       *             input stream does not support reading after close, or
       *             another I/O error occurs.
       * @see        java.io.FilterInputStream#in
       */
      public final void readFully(byte b[]) throws IOException {
          readFully(b, 0, b.length);
      }
  
      /**
!      * See the general contract of the <code>readFully</code>
!      * method of <code>DataInput</code>.
       * <p>
       * Bytes
       * for this operation are read from the contained
       * input stream.
       *
       * @param      b     the buffer into which the data is read.
!      * @param      off   the start offset of the data.
       * @param      len   the number of bytes to read.
       * @exception  EOFException  if this input stream reaches the end before
       *               reading all the bytes.
       * @exception  IOException   the stream has been closed and the contained
       *             input stream does not support reading after close, or
       *             another I/O error occurs.
--- 148,192 ----
      public final int read(byte b[], int off, int len) throws IOException {
          return in.read(b, off, len);
      }
  
      /**
!      * See the general contract of the {@code readFully}
!      * method of {@code DataInput}.
       * <p>
       * Bytes
       * for this operation are read from the contained
       * input stream.
       *
       * @param   b   the buffer into which the data is read.
!      * @throws  NullPointerException If {@code b} is {@code null}.
!      * @throws  EOFException  if this input stream reaches the end before
       *          reading all the bytes.
!      * @throws  IOException   the stream has been closed and the contained
       *          input stream does not support reading after close, or
       *          another I/O error occurs.
       * @see     java.io.FilterInputStream#in
       */
      public final void readFully(byte b[]) throws IOException {
          readFully(b, 0, b.length);
      }
  
      /**
!      * See the general contract of the {@code readFully}
!      * method of {@code DataInput}.
       * <p>
       * Bytes
       * for this operation are read from the contained
       * input stream.
       *
       * @param      b     the buffer into which the data is read.
!      * @param      off   the start offset into the data array {@code b}.
       * @param      len   the number of bytes to read.
+      * @exception  NullPointerException If {@code b} is {@code null}.
+      * @exception  IndexOutOfBoundsException If {@code off} is negative,
+      *             {@code len} is negative, or {@code len} is greater than
+      *             {@code b.length - off}
       * @exception  EOFException  if this input stream reaches the end before
       *             reading all the bytes.
       * @exception  IOException   the stream has been closed and the contained
       *             input stream does not support reading after close, or
       *             another I/O error occurs.