FilterInputStream provides the ability to
* unread data from a stream. It maintains an internal buffer of unread
* data that is supplied to the next read operation. This is conceptually
* similar to mark/reset functionality, except that in this case the
* position to reset the stream to does not need to be known in advance.
* * The default pushback buffer size one byte, but this can be overridden * by the creator of the stream. *
*
* @author Aaron M. Renn (arenn@urbanophile.com)
* @author Warren Levy
* This method will return the number of bytes available from the
* pushback buffer plus the number of bytes available from the
* underlying stream.
*
* @return The number of bytes that can be read before blocking could occur
*
* @exception IOException If an error occurs
*/
public int available() throws IOException
{
return pos + super.available();
}
/**
* This method closes the stream and releases any associated resources.
*
* @exception IOException If an error occurs.
*/
public synchronized void close() throws IOException
{
buf = null;
super.close();
}
/**
* This method returns
* This method will block until the byte can be read.
*
* @return The byte read or -1 if end of stream
*
* @exception IOException If an error occurs
*/
public synchronized int read() throws IOException
{
if (pos < buf.length)
return ((int) buf[pos++]) & 0xFF;
return super.read();
}
/**
* This method read bytes from a stream and stores them into a
* caller supplied buffer. It starts storing the data at index
*
* This method will block until some data can be read.
*
* This method first reads bytes from the pushback buffer in order to
* satisfy the read request. If the pushback buffer cannot provide all
* of the bytes requested, the remaining bytes are read from the
* underlying stream.
*
* @param b The array into which the bytes read should be stored
* @param off The offset into the array to start storing bytes
* @param len The requested number of bytes to read
*
* @return The actual number of bytes read, or -1 if end of stream.
*
* @exception IOException If an error occurs.
*/
public synchronized int read(byte[] b, int off, int len) throws IOException
{
if (off < 0 || len < 0 || off + len > b.length)
throw new ArrayIndexOutOfBoundsException();
int numBytes = Math.min(buf.length - pos, len);
if (numBytes > 0)
{
System.arraycopy (buf, pos, b, off, numBytes);
pos += numBytes;
return numBytes;
}
return super.read(b, off, len);
}
/**
* This method pushes a single byte of data into the pushback buffer.
* The byte pushed back is the one that will be returned as the first byte
* of the next read.
*
* If the pushback buffer is full, this method throws an exception.
*
* The argument to this method is an
* If the pushback buffer cannot hold all of the requested bytes, an
* exception is thrown.
*
* @param b The byte array to be pushed back
*
* @exception IOException If the pushback buffer is full
*/
public synchronized void unread(byte[] b) throws IOException
{
unread(b, 0, b.length);
}
/**
* This method pushed back bytes from the passed in array into the
* pushback buffer. The bytes from
* If the pushback buffer cannot hold all of the requested bytes, an
* exception is thrown.
*
* @param b The byte array to be pushed back
* @param off The index into the array where the bytes to be push start
* @param len The number of bytes to be pushed.
*
* @exception IOException If the pushback buffer is full
*/
public synchronized void unread(byte[] b, int off, int len)
throws IOException
{
if (pos < len)
throw new IOException("Insufficient space in pushback buffer");
// Note the order that these bytes are being added is the opposite
// of what would be done if they were added to the buffer one at a time.
// See the Java Class Libraries book p. 1390.
System.arraycopy(b, off, buf, pos - len, len);
// Don't put this into the arraycopy above, an exception might be thrown
// and in that case we don't want to modify pos.
pos -= len;
}
/**
* This method skips the specified number of bytes in the stream. It
* returns the actual number of bytes skipped, which may be less than the
* requested amount.
*
* This method first discards bytes from the buffer, then calls the
* buf[buf.length - 1] to buf[0]. Thus when
* pos is 0 the buffer is full and buf.length when
* it is empty
*/
protected int pos;
/**
* This method initializes a PushbackInputStream to
* read from the * specified subordinate InputStream
* with a default pushback buffer * size of 1.
*
* @param in The subordinate stream to read from
*/
public PushbackInputStream(InputStream in)
{
this(in, DEFAULT_BUFFER_SIZE);
}
/**
* This method initializes a PushbackInputStream to
* read from the specified subordinate InputStream with
* the specified buffer size
*
* @param in The subordinate InputStream to read from
* @param size The pushback buffer size to use
*/
public PushbackInputStream(InputStream in, int size)
{
super(in);
if (size < 0)
throw new IllegalArgumentException();
buf = new byte[size];
pos = buf.length;
}
/**
* This method returns the number of bytes that can be read from this
* stream before a read can block. A return of 0 indicates that blocking
* might (or might not) occur on the very next read attempt.
* false to indicate that it does
* not support mark/reset functionality.
*
* @return This method returns false to indicate that
* this class does not support mark/reset functionality
*/
public boolean markSupported()
{
return false;
}
/**
* This method always throws an IOException in this class because
* mark/reset functionality is not supported.
*
* @exception IOException Always thrown for this class
*/
public void reset() throws IOException
{
throw new IOException("Mark not supported in this class");
}
/**
* This method reads an unsigned byte from the input stream and returns it
* as an int in the range of 0-255. This method also will return -1 if
* the end of the stream has been reached. The byte returned will be read
* from the pushback buffer, unless the buffer is empty, in which case
* the byte will be read from the underlying stream.
* offset into the buffer and attempts to read
* len bytes. This method can return before reading the
* number of bytes requested. The actual number of bytes read is
* returned as an int. A -1 is returned to indicate the end of the
* stream.
* int. Only the low
* eight bits of this value are pushed back.
*
* @param b The byte to be pushed back, passed as an int
*
* @exception IOException If the pushback buffer is full.
*/
public synchronized void unread(int b) throws IOException
{
if (pos <= 0)
throw new IOException("Insufficient space in pushback buffer");
buf[--pos] = (byte) b;
}
/**
* This method pushes all of the bytes in the passed byte array into
* the pushback bfer. These bytes are pushed in reverse order so that
* the next byte read from the stream after this operation will be
* b[0] followed by b[1], etc.
* b[offset] to
* b[offset] followed by b[offset + 1],
* etc.
* skip method on the underlying InputStream to
* skip additional bytes if necessary.
*
* @param num_bytes The requested number of bytes to skip
*
* @return The actual number of bytes skipped.
*
* @exception IOException If an error occurs
*
* @since 1.2
*/
public synchronized long skip(long n) throws IOException
{
final long origN = n;
if (n > 0L)
{
int numread = (int) Math.min((long) (buf.length - pos), n);
pos += numread;
n -= numread;
n -= super.skip(n);
}
return origN - n;
}
}