src/java.base/share/classes/java/io/DataInput.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) 1995, 2013, 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) 1995, 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
*** 181,193 ****
       * this method, then it may be that some but
       * not all bytes of {@code b} have been
       * updated with data from the input stream.
       *
       * @param     b   the buffer into which the data is read.
!      * @exception  EOFException  if this stream reaches the end before reading
       *               all the bytes.
!      * @exception  IOException   if an I/O error occurs.
       */
      void readFully(byte b[]) throws IOException;
  
      /**
       *
--- 181,194 ----
       * this method, then it may be that some but
       * not all bytes of {@code b} have been
       * updated with data from the input stream.
       *
       * @param   b   the buffer into which the data is read.
!      * @throws  NullPointerException If {@code b} is {@code null}.
!      * @throws  EOFException  if this stream reaches the end before reading
       *          all the bytes.
!      * @throws  IOException   if an I/O error occurs.
       */
      void readFully(byte b[]) throws IOException;
  
      /**
       *
*** 225,239 ****
       * the next one into {@code b[off+1]},
       * and so on. The number of bytes read is,
       * at most, equal to {@code len}.
       *
       * @param     b   the buffer into which the data is read.
!      * @param off  an int specifying the offset into the data.
       * @param len  an int specifying the number of bytes to read.
!      * @exception  EOFException  if this stream reaches the end before reading
       *               all the bytes.
!      * @exception  IOException   if an I/O error occurs.
       */
      void readFully(byte b[], int off, int len) throws IOException;
  
      /**
       * Makes an attempt to skip over
--- 226,244 ----
       * the next one into {@code b[off+1]},
       * and so on. The number of bytes read is,
       * at most, equal to {@code len}.
       *
       * @param   b    the buffer into which the data is read.
!      * @param   off  an int specifying the offset into the data array {@code b}.
       * @param   len  an int specifying the number of bytes to read.
!      * @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}
!      * @throws  EOFException  if this stream reaches the end before reading
       *          all the bytes.
!      * @throws  IOException   if an I/O error occurs.
       */
      void readFully(byte b[], int off, int len) throws IOException;
  
      /**
       * Makes an attempt to skip over