PushbackInputStream adds functionality to another input stream, namely the ability to "push back" or
* "unread" one byte. This is useful in situations where it is convenient for a fragment of code to read an indefinite
* number of data bytes that are delimited by a particular byte value; after reading the terminating byte, the code
* fragment can "unread" it, so that the next read operation on the input stream will reread the byte that was pushed
* back. For example, bytes representing the characters constituting an identifier might be terminated by a byte
* representing an operator character; a method whose job is to read just an identifier can read until it sees the
* operator and then push the operator back to be re-read.
*
* @author David Connelly
* @author Jonathan Payne
* @since JDK1.0
*/
public class PushbackInputStream extends FilterInputStream {
/**
* The pushback buffer.
*
* @since JDK1.1
*/
@Nullable
protected byte[] buf;
/**
* The position within the pushback buffer from which the next byte will be read. When the buffer is empty,
* pos is equal to buf.length; when the buffer is full, pos is equal to zero.
*
* @since JDK1.1
*/
protected int pos;
/**
* Check to make sure that this stream has not been closed
*/
private void ensureOpen() throws IOException {
if (this.in == null) {
throw new IOException("Stream closed");
}
}
/**
* Creates a PushbackInputStream with a pushback buffer of the specified size, and saves
* its argument, the input stream in, for later use. Initially, there is no pushed-back byte (the field
* pushBack is initialized to -1).
*
* @param in
* the input stream from which bytes will be read.
* @param size
* the size of the pushback buffer.
* @exception IllegalArgumentException
* if {@code size <= 0}
* @since JDK1.1
*/
public PushbackInputStream(InputStream in, int size) {
super(in);
if (size <= 0) {
throw new IllegalArgumentException("size <= 0");
}
this.buf = new byte[size];
this.pos = size;
}
/**
* Creates a PushbackInputStream and saves its argument, the input stream in, for later
* use. Initially, there is no pushed-back byte (the field pushBack is initialized to -1).
*
* @param in
* the input stream from which bytes will be read.
*/
public PushbackInputStream(InputStream in) {
this(in, 1);
}
/**
* Reads the next byte of data from this input stream. The value byte is returned as an int in the
* range 0 to 255. If no byte is available because the end of the stream has been reached,
* the value -1 is returned. This method blocks until input data is available, the end of the stream is
* detected, or an exception is thrown.
*
*
* This method returns the most recently pushed-back byte, if there is one, and otherwise calls the
* read method of its underlying input stream and returns whatever value that method returns.
*
* @return the next byte of data, or -1 if the end of the stream has been reached.
* @exception IOException
* if this input stream has been closed by invoking its {@link #close()} method, or an I/O error
* occurs.
* @see java.io.InputStream#read()
*/
@Override
public int read() throws IOException {
ensureOpen();
byte[] buf = this.buf;
assert buf != null;
if (this.pos < buf.length) {
return buf[this.pos++] & 0xff;
}
return super.read();
}
/**
* Reads up to len bytes of data from this input stream into an array of bytes. This method first reads
* any pushed-back bytes; after that, if fewer than len bytes have been read then it reads from the
* underlying input stream. If len is not zero, the method blocks until at least 1 byte of input is
* available; otherwise, no bytes are read and 0 is returned.
*
* @param b
* the buffer into which the data is read.
* @param off
* the start offset in the destination array b
* @param len
* the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or -1 if there is no more data because the
* end of the stream has been reached.
* @exception NullPointerException
* If b is null.
* @exception IndexOutOfBoundsException
* If off is negative, len is negative, or len is greater than
* b.length - off
* @exception IOException
* if this input stream has been closed by invoking its {@link #close()} method, or an I/O error
* occurs.
* @see java.io.InputStream#read(byte[], int, int)
*/
@Override
public int read(@Nullable byte[] b, int off, int len) throws IOException {
ensureOpen();
if (b == null) {
throw new NullPointerException();
} else if (off < 0 || len < 0 || len > b.length - off) {
throw new IndexOutOfBoundsException();
} else if (len == 0) {
return 0;
}
byte[] buf = this.buf;
assert buf != null;
int avail = buf.length - this.pos;
if (avail > 0) {
if (len < avail) {
avail = len;
}
System.arraycopy(buf, this.pos, b, off, avail);
this.pos += avail;
off += avail;
len -= avail;
}
if (len > 0) {
len = super.read(b, off, len);
if (len == -1) {
return avail == 0 ? -1 : avail;
}
return avail + len;
}
return avail;
}
/**
* Pushes back a byte by copying it to the front of the pushback buffer. After this method returns, the next byte to
* be read will have the value (byte)b.
*
* @param b
* the int value whose low-order byte is to be pushed back.
* @exception IOException
* If there is not enough room in the pushback buffer for the byte, or this input stream has been
* closed by invoking its {@link #close()} method.
*/
public void unread(int b) throws IOException {
ensureOpen();
if (this.pos == 0) {
throw new IOException("Push back buffer is full");
}
byte[] buf = this.buf;
assert buf != null;
buf[--this.pos] = (byte) b;
}
/**
* Pushes back a portion of an array of bytes by copying it to the front of the pushback buffer. After this method
* returns, the next byte to be read will have the value b[off], the byte after that will have the
* value b[off+1], and so forth.
*
* @param b
* the byte array to push back.
* @param off
* the start offset of the data.
* @param len
* the number of bytes to push back.
* @exception IOException
* If there is not enough room in the pushback buffer for the specified number of bytes, or this
* input stream has been closed by invoking its {@link #close()} method.
* @since JDK1.1
*/
public void unread(byte[] b, int off, int len) throws IOException {
ensureOpen();
if (len > this.pos) {
throw new IOException("Push back buffer is full");
}
this.pos -= len;
byte[] buf = this.buf;
assert buf != null;
System.arraycopy(b, off, buf, this.pos, len);
}
/**
* Pushes back an array of bytes by copying it to the front of the pushback buffer. After this method returns, the
* next byte to be read will have the value b[0], the byte after that will have the value
* b[1], and so forth.
*
* @param b
* the byte array to push back
* @exception IOException
* If there is not enough room in the pushback buffer for the specified number of bytes, or this
* input stream has been closed by invoking its {@link #close()} method.
* @since JDK1.1
*/
public void unread(byte[] b) throws IOException {
unread(b, 0, b.length);
}
/**
* Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without
* blocking by the next invocation of a method for this input stream. The next invocation might be the same thread
* or another thread. A single read or skip of this many bytes will not block, but may read or skip fewer bytes.
*
*
* The method returns the sum of the number of bytes that have been pushed back and the value returned by
* {@link java.io.FilterInputStream#available available}.
*
* @return the number of bytes that can be read (or skipped over) from the input stream without blocking.
* @exception IOException
* if this input stream has been closed by invoking its {@link #close()} method, or an I/O error
* occurs.
* @see java.io.FilterInputStream#in
* @see java.io.InputStream#available()
*/
@Override
public int available() throws IOException {
ensureOpen();
byte[] buf = this.buf;
assert buf != null;
int n = buf.length - this.pos;
int avail = super.available();
return n > (Integer.MAX_VALUE - avail) ? Integer.MAX_VALUE : n + avail;
}
/**
* Skips over and discards n bytes of data from this input stream. The skip method may,
* for a variety of reasons, end up skipping over some smaller number of bytes, possibly zero. If n is
* negative, no bytes are skipped.
*
*
* The skip method of PushbackInputStream first skips over the bytes in the pushback
* buffer, if any. It then calls the skip method of the underlying input stream if more bytes need to
* be skipped. The actual number of bytes skipped is returned.
*
* @param n
* {@inheritDoc}
* @return {@inheritDoc}
* @exception IOException
* if the stream does not support seek, or the stream has been closed by invoking its
* {@link #close()} method, or an I/O error occurs.
* @see java.io.FilterInputStream#in
* @see java.io.InputStream#skip(long n)
* @since 1.2
*/
@Override
public long skip(long n) throws IOException {
ensureOpen();
if (n <= 0) {
return 0;
}
byte[] buf = this.buf;
assert buf != null;
long pskip = buf.length - this.pos;
if (pskip > 0) {
if (n < pskip) {
pskip = n;
}
this.pos += pskip;
n -= pskip;
}
if (n > 0) {
pskip += super.skip(n);
}
return pskip;
}
/**
* Tests if this input stream supports the mark and reset methods, which it does not.
*
* @return false, since this class does not support the mark and reset
* methods.
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
@Override
public boolean markSupported() {
return false;
}
/**
* Marks the current position in this input stream.
*
*
* The mark method of PushbackInputStream does nothing.
*
* @param readlimit
* the maximum limit of bytes that can be read before the mark position becomes invalid.
* @see java.io.InputStream#reset()
*/
@Override
public synchronized void mark(int readlimit) {
}
/**
* Repositions this stream to the position at the time the mark method was last called on this input
* stream.
*
*
* The method reset for class PushbackInputStream does nothing except throw an
* IOException.
*
* @exception IOException
* if this method is invoked.
* @see java.io.InputStream#mark(int)
* @see java.io.IOException
*/
@Override
public synchronized void reset() throws IOException {
throw new IOException("mark/reset not supported");
}
/**
* Closes this input stream and releases any system resources associated with the stream. Once the stream has been
* closed, further read(), unread(), available(), reset(), or skip() invocations will throw an IOException. Closing
* a previously closed stream has no effect.
*
* @exception IOException
* if an I/O error occurs.
*/
@Override
@SuppressWarnings("null")
public synchronized void close() throws IOException {
InputStream in = this.in;
if (in == null) {
return;
}
in.close();
this.in = null;
this.buf = null;
}
}