Many people continue to be confused about what exactly the available
method returns. In many cases, available will return the complete
size of the stream, leading people to write code that calls available,
allocates a byte array of that size, and does a single read into that
byte array, assuming they will get everything in the stream. This is
clearly not true, and the javadocs for the method could do more to
clarify this.

In addition, it's not clear whether available returns a guarantee, or
merely an estimate. For instance, if available returns 1000, and you
attempt to read 1000 bytes, is it acceptable for the stream to return
only 995 bytes (without blocking, of course)? I believe it is. In
some cases it's not possible to determine exactly how many bytes can
be read without doing all the work (e.g., decoding) to return the bytes.
In such a case, it seems acceptable to return an estimate of the number
of bytes that could be returned, as long as the actual read returns the
correct number of bytes without unnecessarily blocking the caller.
Short reads must always be acceptable.

The javadocs for the available method needs to address these issues, and
probably more I haven't thought of yet.