Summary

Change specification of InputStream.available() to indicate clearly that 0 may be returned when not at end of stream.

Problem

The specification of InputStream.available() does not make it clear that 0 may be returned, even if not at end of stream, i.e., if no bytes may be read but the stream is not exhausted, for example in the case of a socket.

Solution

Change the specification of InputStream.available() to state clearly that 0 may be returned, even if not at end of stream.

Specification

The proposed specification change is as follows.

     /**
-     * Returns an estimate of the number of bytes that can be read (or
-     * skipped over) from this input stream without blocking by the next
-     * invocation of a method for this input stream. The next invocation
-     * 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.
+     * Returns an estimate of the number of bytes that can be read (or skipped
+     * over) from this input stream without blocking, which may be 0, or 0 when
+     * end of stream is detected.  The read might be on 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> Note that while some implementations of {@code InputStream} will return
      * the total number of bytes in the stream, many will not.  It is
      * never correct to use the return value of this method to allocate
      * a buffer intended to hold all data in this stream.
      *
-     * <p> A subclass' implementation of this method may choose to throw an
+     * <p> A subclass's implementation of this method may choose to throw an
      * {@link IOException} if this input stream has been closed by
      * invoking the {@link #close()} method.
      *
-     * <p> The {@code available} method for class {@code InputStream} always
-     * returns {@code 0}.
+     * <p> The {@code available} method of {@code InputStream} always returns
+     * {@code 0}.
      *
      * <p> This method should be overridden by subclasses.
      *
      * @return     an estimate of the number of bytes that can be read (or skipped
      *             over) from this input stream without blocking or {@code 0} when
      *             it reaches the end of the input stream.
      * @exception  IOException if an I/O error occurs.
      */
     public int available() throws IOException {}