Mercurial > hg > openjdk > jdk9 > jdk
changeset 14263:fabd6d558e79
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
| author | bpb |
|---|---|
| date | Wed, 20 Apr 2016 15:06:13 -0700 |
| parents | a7147a466b12 |
| children | 45cd8577db8e |
| files | src/java.base/share/classes/java/io/DataInput.java src/java.base/share/classes/java/io/DataInputStream.java src/java.base/share/classes/java/io/ObjectInputStream.java src/java.base/share/classes/java/io/RandomAccessFile.java |
| diffstat | 4 files changed, 62 insertions(+), 38 deletions(-) [+] |
line wrap: on
line diff
--- a/src/java.base/share/classes/java/io/DataInput.java Wed Apr 20 22:46:47 2016 +0100 +++ b/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/src/java.base/share/classes/java/io/DataInputStream.java Wed Apr 20 22:46:47 2016 +0100 +++ b/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/src/java.base/share/classes/java/io/ObjectInputStream.java Wed Apr 20 22:46:47 2016 +0100 +++ b/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/src/java.base/share/classes/java/io/RandomAccessFile.java Wed Apr 20 22:46:47 2016 +0100 +++ b/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;