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: rriggs, smarks
--- a/jdk/src/java.base/share/classes/java/io/DataInput.java Wed Apr 20 22:46:47 2016 +0100
+++ b/jdk/src/java.base/share/classes/java/io/DataInput.java Wed Apr 20 15:06:13 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -182,10 +182,11 @@
* 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.
+ * @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;
@@ -226,12 +227,16 @@
* 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.
+ * @param b the buffer into which the data is read.
+ * @param off an int specifying the offset in 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;
--- a/jdk/src/java.base/share/classes/java/io/DataInputStream.java Wed Apr 20 22:46:47 2016 +0100
+++ b/jdk/src/java.base/share/classes/java/io/DataInputStream.java Wed Apr 20 15:06:13 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1994, 2006, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -150,38 +150,43 @@
}
/**
- * See the general contract of the <code>readFully</code>
- * method of <code>DataInput</code>.
+ * 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.
- * @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
+ * @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</code>
- * method of <code>DataInput</code>.
+ * 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 of the data.
+ * @param off the start offset in 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.
+ * 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.
--- a/jdk/src/java.base/share/classes/java/io/ObjectInputStream.java Wed Apr 20 22:46:47 2016 +0100
+++ b/jdk/src/java.base/share/classes/java/io/ObjectInputStream.java Wed Apr 20 15:06:13 2016 -0700
@@ -856,10 +856,14 @@
* 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)
*/
@@ -1017,6 +1021,7 @@
* 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.
*/
@@ -1028,8 +1033,12 @@
* 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.
*/
--- a/jdk/src/java.base/share/classes/java/io/RandomAccessFile.java Wed Apr 20 22:46:47 2016 +0100
+++ b/jdk/src/java.base/share/classes/java/io/RandomAccessFile.java Wed Apr 20 15:06:13 2016 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved.
+ * 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
@@ -418,10 +418,11 @@
* read. This method blocks until the requested number of bytes are
* read, the end of the stream is detected, or an exception is thrown.
*
- * @param b the buffer into which the data is read.
- * @exception EOFException if this file reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
+ * @param b the buffer into which the data is read.
+ * @throws NullPointerException if {@code b} is {@code null}.
+ * @throws EOFException if this file reaches the end before reading
+ * all the bytes.
+ * @throws IOException if an I/O error occurs.
*/
public final void readFully(byte b[]) throws IOException {
readFully(b, 0, b.length);
@@ -434,12 +435,16 @@
* read. This method blocks until the requested number of bytes are
* read, the end of the stream is detected, or an exception is thrown.
*
- * @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 file reaches the end before reading
- * all the bytes.
- * @exception IOException if an I/O error occurs.
+ * @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.
+ * @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 file reaches the end before reading
+ * all the bytes.
+ * @throws IOException if an I/O error occurs.
*/
public final void readFully(byte b[], int off, int len) throws IOException {
int n = 0;