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 * |