RFR 8180410: ByteArrayOutputStream should not throw IOExceptions

[Roger Riggs]

Hi Brian,

The use of the word 'equivalent' regardless of the context, only says 
the behavior is the same
it does not mandate the implementation except that it behaves the same.

Since the behavior of the method is already specified, adding the 
'equivalent' statement
only makes it easier for the developer to understand the behavior so it 
would be
fine in an apiNote or just part of the description.  Either way, from a 
conformance point of
view, the statement should be ignored.

If it was in an @implSpec clause, then I'd expect to be able to write a 
test that
checks that the behavior is the same using only the API and not making 
any assumption
about that the API invokes.

$.02, Roger



On 3/21/2018 5:23 PM, Brian Burkhalter wrote:
> On Mar 21, 2018, at 2:21 PM, Stuart Marks <stuart.marks at oracle.com> wrote:
>
>>>> Such a refactoring would be prohibited by an @implSpec.
>>> Why then not an @implNote instead of an @apiNote?
>> The statement that was proposed:
>> This method is equivalent to write(b, 0, b.length).
>> is a statement about the semantics of writeBytes(b). Put another way, it states that the requirements on the behavior of writeBytes(b) are equivalent to those on write(b, 0, b.length). Those are statements about the API.
>>
>> I don't think anything needs to be said about implementation.
> I can see what you are saying now. It would be good to have comments from someone else as well.
>
> Thanks,
>
> Brian