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 */
527 public long skip(long n) throws IOException {
528 long remaining = n;
529 int nr;
530
531 if (n <= 0) {
532 return 0;
533 }
534
535 int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
536 byte[] skipBuffer = new byte[size];
537 while (remaining > 0) {
538 nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
539 if (nr < 0) {
540 break;
541 }
542 remaining -= nr;
543 }
544
545 return n - remaining;
546 }
547
548 /**
549 * Skips over and discards exactly {@code n} bytes of data from this input
550 * stream. If {@code n <= 0}, no bytes are skipped. If {@code n > 0},
551 * then {@code n} bytes of data are skipped unless end of stream is
552 * encountered first, in which case an {@code EOFException} is thrown.
553 *
554 * <p> This method blocks until data is available to skip, end of file is
555 * detected, or an exception is thrown.
556 *
557 * @param n the number of bytes to be skipped.
558 * @throws EOFException if end of stream is encountered before {@code n}
559 * bytes are skipped.
560 * @throws IOException if an I/O error occurs.
561 */
562 public void skipNBytes(long n) throws IOException {
563 // For positive n, invoke skip, which should usually suffice, but if
564 // not, discard single bytes until enough are skipped or EOF is reached.
565 if (n > 0 && (n -= skip(n)) > 0) {
566 while (n > 0 && read() != -1)
567 n--;
568 if (n != 0)
569 throw new EOFException();
570 }
571 }
572
573 /**
574 * Returns an estimate of the number of bytes that can be read (or skipped
575 * over) from this input stream without blocking, which may be 0, or 0 when
576 * end of stream is detected. The read might be on the same thread or
577 * another thread. A single read or skip of this many bytes will not block,
578 * but may read or skip fewer bytes.
579 *
580 * <p> Note that while some implementations of {@code InputStream} will
581 * return the total number of bytes in the stream, many will not. It is
582 * never correct to use the return value of this method to allocate
583 * a buffer intended to hold all data in this stream.
584 *
585 * <p> A subclass's implementation of this method may choose to throw an
586 * {@link IOException} if this input stream has been closed by invoking the
587 * {@link #close()} method.
588 *
589 * <p> The {@code available} method of {@code InputStream} always returns
590 * {@code 0}.
591 *
592 * <p> This method should be overridden by subclasses.
593 *
|