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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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 * not all bytes of {@code b} have been
* updated with data from the input stream. * updated with data from the input stream.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @exception EOFException if this stream reaches the end before reading * @throws NullPointerException if {@code b} is {@code null}.
* all the bytes. * @throws EOFException if this stream reaches the end before reading
* @exception IOException if an I/O error occurs. * all the bytes.
* @throws IOException if an I/O error occurs.
*/ */
void readFully(byte b[]) throws IOException; void readFully(byte b[]) throws IOException;
@ -226,12 +227,16 @@ interface DataInput {
* and so on. The number of bytes read is, * and so on. The number of bytes read is,
* at most, equal to {@code len}. * at most, equal to {@code len}.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @param off an int specifying the offset into the data. * @param off an int specifying the offset in the data array {@code b}.
* @param len an int specifying the number of bytes to read. * @param len an int specifying the number of bytes to read.
* @exception EOFException if this stream reaches the end before reading * @throws NullPointerException if {@code b} is {@code null}.
* all the bytes. * @throws IndexOutOfBoundsException if {@code off} is negative,
* @exception IOException if an I/O error occurs. * {@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; 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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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> * See the general contract of the {@code readFully}
* method of <code>DataInput</code>. * method of {@code DataInput}.
* <p> * <p>
* Bytes * Bytes
* for this operation are read from the contained * for this operation are read from the contained
* input stream. * input stream.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @exception EOFException if this input stream reaches the end before * @throws NullPointerException if {@code b} is {@code null}.
* reading all the bytes. * @throws EOFException if this input stream reaches the end before
* @exception IOException the stream has been closed and the contained * reading all the bytes.
* input stream does not support reading after close, or * @throws IOException the stream has been closed and the contained
* another I/O error occurs. * input stream does not support reading after close, or
* @see java.io.FilterInputStream#in * another I/O error occurs.
* @see java.io.FilterInputStream#in
*/ */
public final void readFully(byte b[]) throws IOException { public final void readFully(byte b[]) throws IOException {
readFully(b, 0, b.length); readFully(b, 0, b.length);
} }
/** /**
* See the general contract of the <code>readFully</code> * See the general contract of the {@code readFully}
* method of <code>DataInput</code>. * method of {@code DataInput}.
* <p> * <p>
* Bytes * Bytes
* for this operation are read from the contained * for this operation are read from the contained
* input stream. * input stream.
* *
* @param b the buffer into which the data is read. * @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. * @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 * @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 * @exception IOException the stream has been closed and the contained
* input stream does not support reading after close, or * input stream does not support reading after close, or
* another I/O error occurs. * 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. * exactly 'length' bytes.
* *
* @param buf the buffer into which the data is read * @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 * @param len the maximum number of bytes read
* @return the actual number of bytes read, -1 is returned when the end of * @return the actual number of bytes read, -1 is returned when the end of
* the stream is reached. * 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. * @throws IOException If an I/O error has occurred.
* @see java.io.DataInputStream#readFully(byte[],int,int) * @see java.io.DataInputStream#readFully(byte[],int,int)
*/ */
@ -1017,6 +1021,7 @@ public class ObjectInputStream
* Reads bytes, blocking until all bytes are read. * Reads bytes, blocking until all bytes are read.
* *
* @param buf the buffer into which the data is 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 EOFException If end of file is reached.
* @throws IOException If other I/O error has occurred. * @throws IOException If other I/O error has occurred.
*/ */
@ -1028,8 +1033,12 @@ public class ObjectInputStream
* Reads bytes, blocking until all bytes are read. * Reads bytes, blocking until all bytes are read.
* *
* @param buf the buffer into which the data is 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 * @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 EOFException If end of file is reached.
* @throws IOException If other I/O error has occurred. * @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. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * 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. This method blocks until the requested number of bytes are
* read, the end of the stream is detected, or an exception is thrown. * read, the end of the stream is detected, or an exception is thrown.
* *
* @param b the buffer into which the data is read. * @param b the buffer into which the data is read.
* @exception EOFException if this file reaches the end before reading * @throws NullPointerException if {@code b} is {@code null}.
* all the bytes. * @throws EOFException if this file reaches the end before reading
* @exception IOException if an I/O error occurs. * all the bytes.
* @throws IOException if an I/O error occurs.
*/ */
public final void readFully(byte b[]) throws IOException { public final void readFully(byte b[]) throws IOException {
readFully(b, 0, b.length); 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. This method blocks until the requested number of bytes are
* read, the end of the stream is detected, or an exception is thrown. * read, the end of the stream is detected, or an exception is thrown.
* *
* @param b the buffer into which the data is read. * @param b 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 b}.
* @param len the number of bytes to read. * @param len the number of bytes to read.
* @exception EOFException if this file reaches the end before reading * @throws NullPointerException if {@code b} is {@code null}.
* all the bytes. * @throws IndexOutOfBoundsException if {@code off} is negative,
* @exception IOException if an I/O error occurs. * {@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 { public final void readFully(byte b[], int off, int len) throws IOException {
int n = 0; int n = 0;