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

InputStream.skipNBytes(long k) to skip exactly k bytes

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: None
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source, binary
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      If an existing subclass implements a method with the same signature then there could be a conflict. No such implementations have been found.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Add java.io.InputStream.skipNBytes(long) to skip forward an exact number of bytes.

      Problem

      The existing method java.io.InputStream.skip(long) does not guarantee that the requested number of bytes will actually be skipped.

      Solution

      Define a new method java.io.InputStream.skipNBytes(long) which will skip exactly the number of bytes requested or throw an exception.

      Specification

      Changes to java.io.InputStream.nullInputStream() documentation:

           * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
           * {@code readNBytes(int)}, {@code skip(long)}, {@code skipNBytes(long)},

      Changes to java.io.InputStream.skip(long) documentation:

           * @return     the actual number of bytes skipped which might be zero.
           * @throws     IOException  if an I/O error occurs.
           * @see        java.io.InputStream#skipNBytes(long)

      New method java.io.InputStream.skipNBytes(long):

          /**
           * Skips over and discards exactly {@code n} bytes of data from this input
           * stream.  If {@code n} is zero, then no bytes are skipped.
           * If {@code n} is negative, then no bytes are skipped.
           * Subclasses may handle the negative value differently.
           *
           * <p> This method blocks until the requested number of bytes have been
           * skipped, end of file is reached, or an exception is thrown.
           *
           * <p> If end of stream is reached before the stream is at the desired
           * position, then an {@code EOFException} is thrown.
           *
           * <p> If an I/O error occurs, then the input stream may be
           * in an inconsistent state. It is strongly recommended that the
           * stream be promptly closed if an I/O error occurs.
           *
           * @implNote
           * Subclasses are encouraged to provide a more efficient implementation
           * of this method.
           *
           * @implSpec
           * If {@code n} is zero or negative, then no bytes are skipped.
           * If {@code n} is positive, the default implementation of this method
           * invokes {@link #skip(long) skip()} with parameter {@code n}.  If the
           * return value of {@code skip(n)} is non-negative and less than {@code n},
           * then {@link #read()} is invoked repeatedly until the stream is {@code n}
           * bytes beyond its position when this method was invoked or end of stream
           * is reached.  If the return value of {@code skip(n)} is negative or
           * greater than {@code n}, then an {@code IOException} is thrown.  Any
           * exception thrown by {@code skip()} or {@code read()} will be propagated.
           *
           * @param      n   the number of bytes to be skipped.
           * @throws     EOFException if end of stream is encountered before the
           *             stream can be positioned {@code n} bytes beyond its position
           *             when this method was invoked.
           * @throws     IOException  if the stream cannot be positioned properly or
           *             if an I/O error occurs.
           * @see        java.io.InputStream#skip(long)
           */
          public void skipNBytes(long n) throws IOException {}

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpb Brian Burkhalter
                Reporter:
                martin Martin Buchholz
                Reviewed By:
                Roger Riggs
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: