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

[Roger Riggs]

Hi Pavel,

On 4/23/2015 5:12 PM, Pavel Rappo wrote:
> 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.
it happens...  many many people have read those descriptions  (or didn't 
because
it was too obvious or thought to be redundant).

>
> 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].
If one concludes that's an empty interval then its ok; it just reads 
oddly and can
make the reader think its wrong.
In some cases it is easier if the upper bound is defined to be exclusive.
Then if lower == upper, its empty.

If better language were constructed for the new method then perhaps it could
be worked back into methods with similar behavior later.  If the wording 
changes
in any significant way, the conformance team will have to go back and 
re-evaluate
it in detail to see if it really has changed.  So I'd leave it alone.

Roger

>
> 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;