ByteArrayOutputStream should not throw IOExceptions

Summary

Add writeBytes method to ByteArrayOutputStream.

Problem

The variant of ByteArrayOutputStream.write which accepts a single byte array parameter is inherited from OutputStream where it is declared to throw an IOException but when invoked on a ByteArrayOutputStream it cannot throw an IOException. Thus use of this method requires a useless try-catch block:

try {
    baos.write(b);
} catch (IOException e) {
    assert false : "cannot get here";
}

Solution

Add a new method ByteArrayOutputStream.writeBytes which does not throw an IOException. Overriding OutputStream.write not to throw an IOException is not a good option as it could cause an unwelcome source incompatibility especially for those that are compiling to multiple releases without specifying --release (or -source/-target).

Specification

Please refer to the attachment specdiff-baos-writeBytes-8180410.zip.

Principal Change

Add ByteArrayOutputStream.writeBytes:

/**
 * Writes the complete contents of the specified byte array
 * to this {@code ByteArrayOutputStream}.
 *
 * @apiNote
 * This method is equivalent to {@link #write(byte[],int,int)
 * write(b, 0, b.length)}.
 *
 * @param   b     the data.
 * @throws  NullPointerException if {@code b} is {@code null}.
 * @since   11
 */
public void writeBytes(byte b[]) {}

Incidental changes

1. Document that write(b,i,i) throws NullPointerException and IndexOutOfBoundsException.
2. Document that writeTo throws NullPointerException.
3. Globally replace verbiage "byte array output stream" with ByteArrayOutputStream.