< prev index next >

src/java.base/share/classes/java/io/InputStream.java

Print this page




  47  * @see     java.io.PushbackInputStream
  48  * @since   1.0
  49  */
  50 public abstract class InputStream implements Closeable {
  51 
  52     // MAX_SKIP_BUFFER_SIZE is used to determine the maximum buffer size to
  53     // use when skipping.
  54     private static final int MAX_SKIP_BUFFER_SIZE = 2048;
  55 
  56     private static final int DEFAULT_BUFFER_SIZE = 8192;
  57 
  58     /**
  59      * Returns a new {@code InputStream} that reads no bytes. The returned
  60      * stream is initially open.  The stream is closed by calling the
  61      * {@code close()} method.  Subsequent calls to {@code close()} have no
  62      * effect.
  63      *
  64      * <p> While the stream is open, the {@code available()}, {@code read()},
  65      * {@code read(byte[])}, {@code read(byte[], int, int)},
  66      * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
  67      * {@code readNBytes(int)}, {@code skip(long)}, and
  68      * {@code transferTo()} methods all behave as if end of stream has been
  69      * reached.  After the stream has been closed, these methods all throw
  70      * {@code IOException}.
  71      *
  72      * <p> The {@code markSupported()} method returns {@code false}.  The
  73      * {@code mark()} method does nothing, and the {@code reset()} method
  74      * throws {@code IOException}.
  75      *
  76      * @return an {@code InputStream} which contains no bytes
  77      *
  78      * @since 11
  79      */
  80     public static InputStream nullInputStream() {
  81         return new InputStream() {
  82             private volatile boolean closed;
  83 
  84             private void ensureOpen() throws IOException {
  85                 if (closed) {
  86                     throw new IOException("Stream closed");
  87                 }
  88             }


 122                 ensureOpen();
 123                 return 0;
 124             }
 125 
 126             @Override
 127             public byte[] readNBytes(int len) throws IOException {
 128                 if (len < 0) {
 129                     throw new IllegalArgumentException("len < 0");
 130                 }
 131                 ensureOpen();
 132                 return new byte[0];
 133             }
 134 
 135             @Override
 136             public long skip(long n) throws IOException {
 137                 ensureOpen();
 138                 return 0L;
 139             }
 140 
 141             @Override








 142             public long transferTo(OutputStream out) throws IOException {
 143                 Objects.requireNonNull(out);
 144                 ensureOpen();
 145                 return 0L;
 146             }
 147 
 148             @Override
 149             public void close() throws IOException {
 150                 closed = true;
 151             }
 152         };
 153     }
 154 
 155     /**
 156      * Reads the next byte of data from the input stream. The value byte is
 157      * returned as an <code>int</code> in the range <code>0</code> to
 158      * <code>255</code>. If no byte is available because the end of the stream
 159      * has been reached, the value <code>-1</code> is returned. This method
 160      * blocks until input data is available, the end of the stream is detected,
 161      * or an exception is thrown.


 496     }
 497 
 498     /**
 499      * Skips over and discards <code>n</code> bytes of data from this input
 500      * stream. The <code>skip</code> method may, for a variety of reasons, end
 501      * up skipping over some smaller number of bytes, possibly <code>0</code>.
 502      * This may result from any of a number of conditions; reaching end of file
 503      * before <code>n</code> bytes have been skipped is only one possibility.
 504      * The actual number of bytes skipped is returned. If {@code n} is
 505      * negative, the {@code skip} method for class {@code InputStream} always
 506      * returns 0, and no bytes are skipped. Subclasses may handle the negative
 507      * value differently.
 508      *
 509      * <p> The <code>skip</code> method implementation of this class creates a
 510      * byte array and then repeatedly reads into it until <code>n</code> bytes
 511      * have been read or the end of the stream has been reached. Subclasses are
 512      * encouraged to provide a more efficient implementation of this method.
 513      * For instance, the implementation may depend on the ability to seek.
 514      *
 515      * @param      n   the number of bytes to be skipped.
 516      * @return     the actual number of bytes skipped.
 517      * @throws     IOException  if an I/O error occurs.

 518      */
 519     public long skip(long n) throws IOException {
 520 
 521         long remaining = n;
 522         int nr;
 523 
 524         if (n <= 0) {
 525             return 0;
 526         }
 527 
 528         int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
 529         byte[] skipBuffer = new byte[size];
 530         while (remaining > 0) {
 531             nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
 532             if (nr < 0) {
 533                 break;
 534             }
 535             remaining -= nr;
 536         }
 537 
 538         return n - remaining;
 539     }
 540 
 541     /**



























































 542      * Returns an estimate of the number of bytes that can be read (or skipped
 543      * over) from this input stream without blocking, which may be 0, or 0 when
 544      * end of stream is detected.  The read might be on the same thread or
 545      * another thread.  A single read or skip of this many bytes will not block,
 546      * but may read or skip fewer bytes.
 547      *
 548      * <p> Note that while some implementations of {@code InputStream} will
 549      * return the total number of bytes in the stream, many will not.  It is
 550      * never correct to use the return value of this method to allocate
 551      * a buffer intended to hold all data in this stream.
 552      *
 553      * <p> A subclass's implementation of this method may choose to throw an
 554      * {@link IOException} if this input stream has been closed by invoking the
 555      * {@link #close()} method.
 556      *
 557      * <p> The {@code available} method of {@code InputStream} always returns
 558      * {@code 0}.
 559      *
 560      * <p> This method should be overridden by subclasses.
 561      *




  47  * @see     java.io.PushbackInputStream
  48  * @since   1.0
  49  */
  50 public abstract class InputStream implements Closeable {
  51 
  52     // MAX_SKIP_BUFFER_SIZE is used to determine the maximum buffer size to
  53     // use when skipping.
  54     private static final int MAX_SKIP_BUFFER_SIZE = 2048;
  55 
  56     private static final int DEFAULT_BUFFER_SIZE = 8192;
  57 
  58     /**
  59      * Returns a new {@code InputStream} that reads no bytes. The returned
  60      * stream is initially open.  The stream is closed by calling the
  61      * {@code close()} method.  Subsequent calls to {@code close()} have no
  62      * effect.
  63      *
  64      * <p> While the stream is open, the {@code available()}, {@code read()},
  65      * {@code read(byte[])}, {@code read(byte[], int, int)},
  66      * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
  67      * {@code readNBytes(int)}, {@code skip(long)}, {@code skipNBytes(long)},
  68      * and {@code transferTo()} methods all behave as if end of stream has been
  69      * reached.  After the stream has been closed, these methods all throw
  70      * {@code IOException}.
  71      *
  72      * <p> The {@code markSupported()} method returns {@code false}.  The
  73      * {@code mark()} method does nothing, and the {@code reset()} method
  74      * throws {@code IOException}.
  75      *
  76      * @return an {@code InputStream} which contains no bytes
  77      *
  78      * @since 11
  79      */
  80     public static InputStream nullInputStream() {
  81         return new InputStream() {
  82             private volatile boolean closed;
  83 
  84             private void ensureOpen() throws IOException {
  85                 if (closed) {
  86                     throw new IOException("Stream closed");
  87                 }
  88             }


 122                 ensureOpen();
 123                 return 0;
 124             }
 125 
 126             @Override
 127             public byte[] readNBytes(int len) throws IOException {
 128                 if (len < 0) {
 129                     throw new IllegalArgumentException("len < 0");
 130                 }
 131                 ensureOpen();
 132                 return new byte[0];
 133             }
 134 
 135             @Override
 136             public long skip(long n) throws IOException {
 137                 ensureOpen();
 138                 return 0L;
 139             }
 140 
 141             @Override
 142             public void skipNBytes(long n) throws IOException {
 143                 ensureOpen();
 144                 if (n > 0) {
 145                     throw new EOFException();
 146                 }
 147             }
 148 
 149             @Override
 150             public long transferTo(OutputStream out) throws IOException {
 151                 Objects.requireNonNull(out);
 152                 ensureOpen();
 153                 return 0L;
 154             }
 155 
 156             @Override
 157             public void close() throws IOException {
 158                 closed = true;
 159             }
 160         };
 161     }
 162 
 163     /**
 164      * Reads the next byte of data from the input stream. The value byte is
 165      * returned as an <code>int</code> in the range <code>0</code> to
 166      * <code>255</code>. If no byte is available because the end of the stream
 167      * has been reached, the value <code>-1</code> is returned. This method
 168      * blocks until input data is available, the end of the stream is detected,
 169      * or an exception is thrown.


 504     }
 505 
 506     /**
 507      * Skips over and discards <code>n</code> bytes of data from this input
 508      * stream. The <code>skip</code> method may, for a variety of reasons, end
 509      * up skipping over some smaller number of bytes, possibly <code>0</code>.
 510      * This may result from any of a number of conditions; reaching end of file
 511      * before <code>n</code> bytes have been skipped is only one possibility.
 512      * The actual number of bytes skipped is returned. If {@code n} is
 513      * negative, the {@code skip} method for class {@code InputStream} always
 514      * returns 0, and no bytes are skipped. Subclasses may handle the negative
 515      * value differently.
 516      *
 517      * <p> The <code>skip</code> method implementation of this class creates a
 518      * byte array and then repeatedly reads into it until <code>n</code> bytes
 519      * have been read or the end of the stream has been reached. Subclasses are
 520      * encouraged to provide a more efficient implementation of this method.
 521      * For instance, the implementation may depend on the ability to seek.
 522      *
 523      * @param      n   the number of bytes to be skipped.
 524      * @return     the actual number of bytes skipped which might be zero.
 525      * @throws     IOException  if an I/O error occurs.
 526      * @see        java.io.InputStream#skipNBytes(long)
 527      */
 528     public long skip(long n) throws IOException {

 529         long remaining = n;
 530         int nr;
 531 
 532         if (n <= 0) {
 533             return 0;
 534         }
 535 
 536         int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
 537         byte[] skipBuffer = new byte[size];
 538         while (remaining > 0) {
 539             nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
 540             if (nr < 0) {
 541                 break;
 542             }
 543             remaining -= nr;
 544         }
 545 
 546         return n - remaining;
 547     }
 548 
 549     /**
 550      * Skips over and discards exactly {@code n} bytes of data from this input
 551      * stream.  If {@code n} is zero, then no bytes are skipped.
 552      * If {@code n} is negative, then no bytes are skipped.
 553      * Subclasses may handle the negative value differently.
 554      *
 555      * <p> This method blocks until the requested number of bytes have been
 556      * skipped, end of file is reached, or an exception is thrown.
 557      *
 558      * <p> If end of stream is reached before the stream is at the desired
 559      * position, then an {@code EOFException} is thrown.
 560      *
 561      * <p> If an I/O error occurs, then the input stream may be
 562      * in an inconsistent state. It is strongly recommended that the
 563      * stream be promptly closed if an I/O error occurs.
 564      *
 565      * @implNote
 566      * Subclasses are encouraged to provide a more efficient implementation
 567      * of this method.
 568      *
 569      * @implSpec
 570      * If {@code n} is zero or negative, then no bytes are skipped.
 571      * If {@code n} is positive, the default implementation of this method
 572      * invokes {@link #skip(long) skip()} with parameter {@code n}.  If the
 573      * return value of {@code skip(n)} is non-negative and less than {@code n},
 574      * then {@link #read()} is invoked repeatedly until the stream is {@code n}
 575      * bytes beyond its position when this method was invoked or end of stream
 576      * is reached.  If the return value of {@code skip(n)} is negative or
 577      * greater than {@code n}, then an {@code IOException} is thrown.  Any
 578      * exception thrown by {@code skip()} or {@code read()} will be propagated.
 579      *
 580      * @param      n   the number of bytes to be skipped.
 581      * @throws     EOFException if end of stream is encountered before the
 582      *             stream can be positioned {@code n} bytes beyond its position
 583      *             when this method was invoked.
 584      * @throws     IOException  if the stream cannot be positioned properly or
 585      *             if an I/O error occurs.
 586      * @see        java.io.InputStream#skip(long)
 587      */
 588     public void skipNBytes(long n) throws IOException {
 589         if (n > 0) {
 590             long ns = skip(n);
 591             if (ns >= 0 && ns < n) { // skipped too few bytes
 592                 // adjust number to skip
 593                 n -= ns;
 594                 // read until requested number skipped or EOS reached
 595                 while (n > 0 && read() != -1) {
 596                     n--;
 597                 }
 598                 // if not enough skipped, then EOFE
 599                 if (n != 0) {
 600                     throw new EOFException();
 601                 }
 602             } else if (ns != n) { // skipped negative or too many bytes
 603                 throw new IOException("Unable to skip exactly");
 604             }
 605         }
 606     }
 607 
 608     /**
 609      * Returns an estimate of the number of bytes that can be read (or skipped
 610      * over) from this input stream without blocking, which may be 0, or 0 when
 611      * end of stream is detected.  The read might be on the same thread or
 612      * another thread.  A single read or skip of this many bytes will not block,
 613      * but may read or skip fewer bytes.
 614      *
 615      * <p> Note that while some implementations of {@code InputStream} will
 616      * return the total number of bytes in the stream, many will not.  It is
 617      * never correct to use the return value of this method to allocate
 618      * a buffer intended to hold all data in this stream.
 619      *
 620      * <p> A subclass's implementation of this method may choose to throw an
 621      * {@link IOException} if this input stream has been closed by invoking the
 622      * {@link #close()} method.
 623      *
 624      * <p> The {@code available} method of {@code InputStream} always returns
 625      * {@code 0}.
 626      *
 627      * <p> This method should be overridden by subclasses.
 628      *


< prev index next >