Summary

Add a method InputStream.readNBytes(int len) to read up to len bytes from an input stream and return them in a byte array.

Problem

Using the existing InputStream.readAllBytes() can result in excessive memory allocation if the number of bytes available is larger than expected. Limiting the number of bytes to read to a given upper bound can guard against excessive unexpected input while not requiring an array allocation for the full remaining size of the stream.

Solution

Add to InputStream a method readNBytes(int len) which reads at most len bytes.

Specification

Add a new method readNBytes(int):

    /**
     * Reads up to a specified number of bytes from the input stream. This
     * method blocks until the requested number of bytes have been read, end
     * of stream is detected, or an exception is thrown. This method does not
     * close the input stream.
     *
     * <p> The length of the returned array equals the number of bytes read
     * from the stream. If {@code len} is zero, then no bytes are read and
     * an empty byte array is returned. Otherwise, up to {@code len} bytes
     * are read from the stream. Fewer than {@code len} bytes may be read if
     * end of stream is encountered.
     *
     * <p> When this stream reaches end of stream, further invocations of this
     * method will return an empty byte array.
     *
     * <p> Note that this method is intended for simple cases where it is
     * convenient to read the specified number of bytes into a byte array. The
     * total amount of memory allocated by this method is proportional to the
     * number of bytes read from the stream which is bounded by {@code len}.
     * Therefore, the method may be safely called with very large values of
     * {@code len} provided sufficient memory is available.
     *
     * <p> The behavior for the case where the input stream is <i>asynchronously
     * closed</i>, or the thread interrupted during the read, is highly input
     * stream specific, and therefore not specified.
     *
     * <p> If an I/O error occurs reading from the input stream, then it may do
     * so after some, but not all, bytes have been read. Consequently the input
     * stream may not be at end of stream and may be in an inconsistent state.
     * It is strongly recommended that the stream be promptly closed if an I/O
     * error occurs.
     *
     * @implNote
     * The number of bytes allocated to read data from this stream and return
     * the result is bounded by {@code 2*(long)len}, inclusive.
     *
     * @param len the maximum number of bytes to read
     * @return a byte array containing the bytes read from this input stream
     * @throws IllegalArgumentException if {@code length} is negative
     * @throws IOException if an I/O error occurs
     * @throws OutOfMemoryError if an array of the required size cannot be
     *         allocated.
     *
     * @since 11
     */
    public byte[] readNBytes(int len) throws IOException {}

InputStream.nullInputStream():

Modify the nullInputStream method specification to mention readNBytes(int):

     /**
      * Returns a new {@code InputStream} that reads no bytes. The returned
      * stream is initially open.  The stream is closed by calling the
      * {@code close()} method.  Subsequent calls to {@code close()} have no
      * effect.
      *
      * <p> While the stream is open, the {@code available()}, {@code read()},
      * {@code read(byte[])}, {@code read(byte[], int, int)},
-     * {@code readAllBytes()}, {@code readNBytes()}, {@code skip()}, and
+     * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
+     * {@code readNBytes(int)}, {@code skip(long)}, and
      * {@code transferTo()} methods all behave as if end of stream has been
      * reached.  After the stream has been closed, these methods all throw
      * {@code IOException}.
      *
      * <p> The {@code markSupported()} method returns {@code false}.  The
      * {@code mark()} method does nothing, and the {@code reset()} method
      * throws {@code IOException}.
      *
      * @return an {@code InputStream} which contains no bytes
      *
      * @since 11
      */
     public static InputStream nullInputStream() {}

InputStream.readAllBytes():

Add an @implSpec annotation to indicate that readAllBytes() invokes readNBytes(Integer.MAX_VALUE). Remove a sentence from the OutOfMemoryError specification.

+     * @implSpec
+     * This method invokes {@link #readNBytes(int)} with a length of
+     * {@link Integer#MAX_VALUE}.
+     *
      * @return a byte array containing the bytes read from this input stream
      * @throws IOException if an I/O error occurs
      * @throws OutOfMemoryError if an array of the required size cannot be
-     *         allocated. For example, if an array larger than {@code 2GB} would
-     *         be required to store the bytes.
+     *         allocated.
      *
      * @since 9
      */
     public byte[] readAllBytes() throws IOException {}