Summary
Change specification of java.io.FilterInputStream to indicate that not all InputStream methods are overriden.
Problem
Currently the class specification of FIlterInputStream states:
"The class FilterInputStream itself simply overrides all methods of InputStream with versions that pass all requests to the contained input stream."
which is incorrect as not all methods of InputStream are overridden, notably not readAllBytes(), readNBytes(), skipNBytes() and transferTo().
Solution
Change FilterInputStream class specification to read:
"The class FilterInputStream itself simply overrides select methods of InputStream with versions that pass all requests to the wrapped input stream"
Specification
The only substantive change is to the class specification. The numerous incidental changes add @Override and @implSpec annotations and make a few minor formatting and verbiage changes.
@@ -26,18 +26,14 @@
package java.io;
/**
- * A {@code FilterInputStream} contains
- * some other input stream, which it uses as
- * its basic source of data, possibly transforming
- * the data along the way or providing additional
- * functionality. The class {@code FilterInputStream}
- * itself simply overrides all methods of
- * {@code InputStream} with versions that
- * pass all requests to the contained input
- * stream. Subclasses of {@code FilterInputStream}
- * may further override some of these methods
- * and may also provide additional methods
- * and fields.
+ * A {@code FilterInputStream} wraps some other input stream, which it uses as
+ * its basic source of data, possibly transforming the data along the way or
+ * providing additional functionality. The class {@code FilterInputStream}
+ * itself simply overrides select methods of {@code InputStream} with versions
+ * that pass all requests to the wrapped input stream. Subclasses of
+ * {@code FilterInputStream} may of course override any methods declared or
+ * inherited by {@code FilterInputStream}, and may also provide additional
+ * fields and methods.
*
* @author Jonathan Payne
* @since 1.0
@@ -69,15 +65,16 @@ public class FilterInputStream extends InputStream {
* {@code -1} is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception
* is thrown.
- * <p>
- * This method
- * simply performs {@code in.read()} and returns the result.
+ *
+ * @implSpec
+ * This method simply performs {@code in.read()} and returns the result.
*
* @return the next byte of data, or {@code -1} if the end of the
* stream is reached.
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
+ @Override
public int read() throws IOException {
return in.read();
}
@@ -86,7 +83,8 @@ public class FilterInputStream extends InputStream {
* Reads up to {@code b.length} bytes of data from this
* input stream into an array of bytes. This method blocks until some
* input is available.
- * <p>
+ *
+ * @implSpec
* This method simply performs the call
* {@code read(b, 0, b.length)} and returns
* the result. It is important that it does
@@ -102,6 +100,7 @@ public class FilterInputStream extends InputStream {
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#read(byte[], int, int)
*/
+ @Override
public int read(byte[] b) throws IOException {
return read(b, 0, b.length);
}
@@ -111,7 +110,8 @@ public class FilterInputStream extends InputStream {
* into an array of bytes. If {@code len} is not zero, the method
* blocks until some input is available; otherwise, no
* bytes are read and {@code 0} is returned.
- * <p>
+ *
+ * @implSpec
* This method simply performs {@code in.read(b, off, len)}
* and returns the result.
*
@@ -128,6 +128,7 @@ public class FilterInputStream extends InputStream {
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
+ @Override
public int read(byte[] b, int off, int len) throws IOException {
return in.read(b, off, len);
}
@@ -138,13 +139,15 @@ public class FilterInputStream extends InputStream {
* reasons, end up skipping over some smaller number of bytes,
* possibly {@code 0}. The actual number of bytes skipped is
* returned.
- * <p>
- * This method simply performs {@code in.skip(n)}.
+ *
+ * @implSpec
+ * This method simply performs {@code in.skip(n)} and returns the result.
*
* @param n the number of bytes to be skipped.
* @return the actual number of bytes skipped.
* @throws IOException if {@code in.skip(n)} throws an IOException.
*/
+ @Override
public long skip(long n) throws IOException {
return in.skip(n);
}
@@ -155,13 +158,15 @@ public class FilterInputStream extends InputStream {
* caller of a method for this input stream. The next caller might be
* the same thread or another thread. A single read or skip of this
* many bytes will not block, but may read or skip fewer bytes.
- * <p>
- * This method returns the result of {@link #in in}.available().
*
- * @return an estimate of the number of bytes that can be read (or skipped
- * over) from this input stream without blocking.
+ * @implSpec
+ * This method returns the result of {@code in.available()}.
+ *
+ * @return an estimate of the number of bytes that can be read (or
+ * skipped over) from this input stream without blocking.
* @throws IOException if an I/O error occurs.
*/
+ @Override
public int available() throws IOException {
return in.available();
}
@@ -169,12 +174,14 @@ public class FilterInputStream extends InputStream {
/**
* Closes this input stream and releases any system resources
* associated with the stream.
- * This
- * method simply performs {@code in.close()}.
+ *
+ * @implSpec
+ * This method simply performs {@code in.close()}.
*
* @throws IOException if an I/O error occurs.
* @see java.io.FilterInputStream#in
*/
+ @Override
public void close() throws IOException {
in.close();
}
@@ -187,7 +194,8 @@ public class FilterInputStream extends InputStream {
* The {@code readlimit} argument tells this input stream to
* allow that many bytes to be read before the mark position gets
* invalidated.
- * <p>
+ *
+ * @implSpec
* This method simply performs {@code in.mark(readlimit)}.
*
* @param readlimit the maximum limit of bytes that can be read before
@@ -195,6 +203,7 @@ public class FilterInputStream extends InputStream {
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#reset()
*/
+ @Override
public synchronized void mark(int readlimit) {
in.mark(readlimit);
}
@@ -203,9 +212,6 @@ public class FilterInputStream extends InputStream {
* Repositions this stream to the position at the time the
* {@code mark} method was last called on this input stream.
* <p>
- * This method
- * simply performs {@code in.reset()}.
- * <p>
* Stream marks are intended to be used in
* situations where you need to read ahead a little to see what's in
* the stream. Often this is most easily done by invoking some
@@ -215,11 +221,15 @@ public class FilterInputStream extends InputStream {
* If this happens within readlimit bytes, it allows the outer
* code to reset the stream and try another parser.
*
+ * @implSpec
+ * This method simply performs {@code in.reset()}.
+ *
* @throws IOException if the stream has not been marked or if the
* mark has been invalidated.
* @see java.io.FilterInputStream#in
* @see java.io.FilterInputStream#mark(int)
*/
+ @Override
public synchronized void reset() throws IOException {
in.reset();
}
@@ -227,8 +237,9 @@ public class FilterInputStream extends InputStream {
/**
* Tests if this input stream supports the {@code mark}
* and {@code reset} methods.
- * This method
- * simply performs {@code in.markSupported()}.
+ *
+ * @implSpec
+ * This method simply performs {@code in.markSupported()}.
*
* @return {@code true} if this stream type supports the
* {@code mark} and {@code reset} method;
@@ -237,6 +248,7 @@ public class FilterInputStream extends InputStream {
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
+ @Override
public boolean markSupported() {
return in.markSupported();
}
- csr of
-
JDK-8273513 Make java.io.FilterInputStream specification more precise about overrides
- Resolved