RFR [9] Add blocking bulk read to java.io.InputStream

[Pavel Rappo]

Hey Roger,

1. Good catch! This thing also applies to java.io.InputStream.read(byte[], int, int):

     * <p> In every case, elements <code>b[0]</code> through
     * <code>b[off]</code> and elements <code>b[off+len]</code> through
     * <code>b[b.length-1]</code> are unaffected.

I suppose the javadoc for the method proposed by Chris has started its life as a
copy of the javadoc read(byte[], int, int) which was assumed to be perfectly
polished. Unfortunately it was a false assumption.

2. About awkward sentences. This paragraph also has to be rephrased for the same reason:

     * <p> The first byte read is stored into element {@code b[off]}, the next
     * one in to {@code b[off+1]}, and so on. The number of bytes read is, at
     * most, equal to {@code len}. Let <i>k</i> be the number of bytes actually
     * read; these bytes will be stored in elements {@code b[off]} through
     * {@code b[off+}<i>k</i>{@code -1]}, leaving elements {@code b[off+}<i>k</i>
     * {@code ]} through {@code b[off+len-1]} unaffected.

If k == 0 then spec claims to store values in b[off]... b[off - 1].

The former thing (1) is a real bug, the latter is... I don't know, do we need
this level of strictness or should we assume it's obvious?

-Pavel

> On 23 Apr 2015, at 21:25, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> 
> A minor inconsistency about the unmodified contents of b[off].
> 
> * <p> The first byte read is stored into element {@code b[off]}
> 
> vs.
> 
>  * <p> In every case, elements {@code b[0]} through {@code b[off *- 1*]} and
>  * elements__{@code b[off+len]} through {@code b[b.length-1]} are unaffected.
> 
> I think there's a missing -1;  and perhaps an awkward sentence when off = 0;