1berry/openjdk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

8154183: (spec) Spec of read(byte[],int,int) and readFully(byte[],int,int) is confusing/incomplete

Browse Source 
Clarify and expand specification of ObjectInputStream.read(byte[],int,int) and both variants of {DataInput,DataInputStream,ObjectInputStream,RandomAccessfile}.readFully().

Reviewed-by: rriggs, smarks
This commit is contained in:
Brian Burkhalter 2016-04-20 15:06:13 -07:00
parent 29fc25717a
commit 6e3d77a8ba
4 changed files with 62 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
jdk/src/java.base/share/classes/java/io/DataInput.java
View File

@ -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 @@ interface DataInput {
* 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 @@ interface DataInput {
* 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;

33
jdk/src/java.base/share/classes/java/io/DataInputStream.java
View File

@ -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 @@ class DataInputStream extends FilterInputStream implements DataInput {
}
/**
* 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.

13
jdk/src/java.base/share/classes/java/io/ObjectInputStream.java
View File

@ -856,10 +856,14 @@ public class ObjectInputStream
* 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 @@ public class ObjectInputStream
* 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 @@ public class ObjectInputStream
* 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.
*/

27
jdk/src/java.base/share/classes/java/io/RandomAccessFile.java
View File

@ -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 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
* 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 @@ public class RandomAccessFile implements DataOutput, DataInput, Closeable {
* 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;