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();
     }