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.
479 * @throws NullPointerException if {@code b} is {@code null}
480 * @throws IndexOutOfBoundsException If {@code off} is negative, {@code len}
481 * is negative, or {@code len} is greater than {@code b.length - off}
482 *
483 * @since 9
484 */
485 public int readNBytes(byte[] b, int off, int len) throws IOException {
486 Objects.checkFromIndexSize(off, len, b.length);
487
488 int n = 0;
489 while (n < len) {
490 int count = read(b, off + n, len - n);
491 if (count < 0)
492 break;
493 n += count;
494 }
495 return n;
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}.
|
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.
487 * @throws NullPointerException if {@code b} is {@code null}
488 * @throws IndexOutOfBoundsException If {@code off} is negative, {@code len}
489 * is negative, or {@code len} is greater than {@code b.length - off}
490 *
491 * @since 9
492 */
493 public int readNBytes(byte[] b, int off, int len) throws IOException {
494 Objects.checkFromIndexSize(off, len, b.length);
495
496 int n = 0;
497 while (n < len) {
498 int count = read(b, off + n, len - n);
499 if (count < 0)
500 break;
501 n += count;
502 }
503 return n;
504 }
505
506 /**
507 * Reads and discards up to {@code n} bytes of data from this input
508 * stream. If {@code n <= 0}, no bytes are skipped. An
509 * {@code EOFException} may optionally be thrown if end of stream is
510 * encountered before the requested number of bytes has been skipped.
511 *
512 * <p> This method blocks until data is available to skip, end of file is
513 * detected, or an exception is thrown.
514 *
515 * @param n the number of bytes to be skipped.
516 * @return the actual number of bytes skipped which might be zero.
517 * @throws EOFException if {@code throwOnEOF} is {@code true} and end
518 * of stream is encountered before {@code n} bytes are skipped.
519 * @throws IOException if an I/O error occurs.
520 */
521 private long discardNBytes(long n, boolean throwOnEOF) throws IOException {
522 if (n <= 0) {
523 return 0;
524 }
525
526 long remaining = n;
527 int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
528 byte[] skipBuffer = new byte[size];
529
530 while (remaining > 0) {
531 int nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
532 if (nr < 0) {
533 if (throwOnEOF) {
534 throw new EOFException();
535 }
536 break;
537 }
538 remaining -= nr;
539 }
540
541 return n - remaining;
542 }
543
544 /**
545 * Skips over and discards <code>n</code> bytes of data from this input
546 * stream. The <code>skip</code> method may, for a variety of reasons, end
547 * up skipping over some smaller number of bytes, possibly <code>0</code>.
548 * This may result from any of a number of conditions; reaching end of file
549 * before <code>n</code> bytes have been skipped is only one possibility.
550 * The actual number of bytes skipped is returned. If {@code n} is
551 * negative, the {@code skip} method for class {@code InputStream} always
552 * returns 0, and no bytes are skipped. Subclasses may handle the negative
553 * value differently.
554 *
555 * <p> The <code>skip</code> method implementation of this class creates a
556 * byte array and then repeatedly reads into it until <code>n</code> bytes
557 * have been read or the end of the stream has been reached. Subclasses are
558 * encouraged to provide a more efficient implementation of this method.
559 * For instance, the implementation may depend on the ability to seek.
560 *
561 * @param n the number of bytes to be skipped.
562 * @return the actual number of bytes skipped which might be zero.
563 * @throws IOException if an I/O error occurs.
564 */
565 public long skip(long n) throws IOException {
566 return discardNBytes(n, false);
567 }
568
569 /**
570 * Skips over and discards exactly {@code n} bytes of data from this input
571 * stream. If {@code n <= 0}, no bytes are skipped. If {@code n > 0},
572 * then {@code n} bytes of data are skipped unless end of stream is
573 * encountered first, in which case an {@code EOFException} is thrown.
574 *
575 * <p> This method blocks until data is available to skip, end of file is
576 * detected, or an exception is thrown.
577 *
578 * @param n the number of bytes to be skipped.
579 * @throws EOFException if end of stream is encountered before {@code n}
580 * bytes are skipped.
581 * @throws IOException if an I/O error occurs.
582 */
583 public void skipNBytes(long n) throws IOException {
584 if (n > 0) {
585 // Invoke skip() so as to avail of any subclass efficiency
586 long ns = skip(n);
587
588 // If not enough skipped, read and discard bytes, failing on EOF
589 if (ns != n) {
590 discardNBytes(n - ns, true);
591 }
592 }
593 }
594
595 /**
596 * Returns an estimate of the number of bytes that can be read (or skipped
597 * over) from this input stream without blocking, which may be 0, or 0 when
598 * end of stream is detected. The read might be on the same thread or
599 * another thread. A single read or skip of this many bytes will not block,
600 * but may read or skip fewer bytes.
601 *
602 * <p> Note that while some implementations of {@code InputStream} will
603 * return the total number of bytes in the stream, many will not. It is
604 * never correct to use the return value of this method to allocate
605 * a buffer intended to hold all data in this stream.
606 *
607 * <p> A subclass's implementation of this method may choose to throw an
608 * {@link IOException} if this input stream has been closed by invoking the
609 * {@link #close()} method.
610 *
611 * <p> The {@code available} method of {@code InputStream} always returns
612 * {@code 0}.
|