Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8194956

Add InputStream readNBytes(int len)



    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: core-libs
    • Labels:
    • Subcomponent:
    • Compatibility Risk:
    • Interface Kind:
      Java API
    • Scope:



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


      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.


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


      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 {}


      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() {}


      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 {}


          Issue Links



              bpb Brian Burkhalter
              chegar Chris Hegarty
              Reviewed By:
              Alan Bateman, Chris Hegarty, Roger Riggs, Stuart Marks
              0 Vote for this issue
              3 Start watching this issue