java.io
Class PushbackInputStream

java.lang.Object
  java.io.InputStream
      java.io.FilterInputStream
          java.io.PushbackInputStream

All Implemented Interfaces:

Closeable

public class PushbackInputStream
extends FilterInputStream

PushbackInputStream is a filter class which allows bytes read to be pushed back into the stream so that they can be reread. Parsers may find this useful. There is a progammable limit to the number of bytes which may be pushed back. If the buffer of pushed back bytes is empty, bytes are read from the source input stream.

Field Summary

protected byte[]	buf The byte array containing the bytes to read.
protected int	pos The current position within the byte array buf.

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

PushbackInputStream(InputStream in)
Constructs a new PushbackInputStream on the InputStream in.

PushbackInputStream(InputStream in, int size)
Constructs a new PushbackInputStream on the InputStream in.

Method Summary

int	available() Returns a int representing then number of bytes that are available before this PushbackInputStream will block.
void	close() Close this PushbackInputStream.
void	mark(int readlimit) Make a mark of the current position in the stream but the mark method does nothing.
boolean	markSupported() Returns a boolean indicating whether or not this PushbackInputStream supports mark() and reset().
int	read() Reads a single byte from this PushbackInputStream and returns the result as an int.
int	read(byte[] buffer, int offset, int length) Reads at most length bytes from this PushbackInputStream and stores them in byte array buffer starting at offset.
void	reset() Reset current position to the mark made previously int the stream, but the reset method will throw IOException and do nothing else if called.
long	skip(long count) Skips count number of bytes in this PushbackInputStream.
void	unread(byte[] buffer) Push back all the bytes in buffer.
void	unread(byte[] buffer, int offset, int length) Push back length number of bytes in buffer starting at offset.
void	unread(int oneByte) Push back one byte.

Methods inherited from class java.io.FilterInputStream

read

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

buf

protected byte[] buf

The byte array containing the bytes to read.

pos

protected int pos

The current position within the byte array buf. A value equal to buf.length indicates no bytes available. A value of 0 indicates the buffer is full.

Constructor Detail

PushbackInputStream

public PushbackInputStream(InputStream in)

Constructs a new PushbackInputStream on the InputStream in. The size of the pushback buffer is set to the default, or 1 byte.

Parameters:

in - the InputStream to allow pushback operations on.

PushbackInputStream

public PushbackInputStream(InputStream in,
                           int size)

Constructs a new PushbackInputStream on the InputStream in. The size of the pushback buffer is set to size.

Parameters:

in - the InputStream to allow pushback operations on.

size - the size of the pushback buffer (size>=0).

Method Detail

available

public int available()
              throws IOException

Returns a int representing then number of bytes that are available before this PushbackInputStream will block. This method returns the number of bytes available in the pushback buffer plus those available in the target stream.

Overrides:

available in class FilterInputStream

Returns:

int the number of bytes available before blocking.

Throws:

IOException - If an error occurs in this stream.

close

public void close()
           throws IOException

Close this PushbackInputStream. This implementation closes the target stream.

Specified by:

close in interface Closeable

Overrides:

close in class FilterInputStream

Throws:

IOException - If an error occurs attempting to close this stream.

markSupported

public boolean markSupported()

Returns a boolean indicating whether or not this PushbackInputStream supports mark() and reset(). This implementation always returns false since PushbackInputStreams do not support mark/reset.

Overrides:

markSupported in class FilterInputStream

Returns:

boolean indicates whether or not mark() and reset() are supported.

read

public int read()
         throws IOException

Reads a single byte from this PushbackInputStream and returns the result as an int. The low-order byte is returned or -1 of the end of stream was encountered. If the pushback buffer does not contain any available bytes then a byte from the target input stream is returned.

Overrides:

read in class FilterInputStream

Returns:

int The byte read or -1 if end of stream.

Throws:

IOException - If an IOException occurs.

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IOException

Reads at most length bytes from this PushbackInputStream and stores them in byte array buffer starting at offset. Answer the number of bytes actually read or -1 if no bytes were read and end of stream was encountered. This implementation reads bytes from the pushback buffer first, then the target stream if more bytes are required to satisfy count.

Overrides:

read in class FilterInputStream

Parameters:

buffer - the byte array in which to store the read bytes.

offset - the offset in buffer to store the read bytes.

length - the maximum number of bytes to store in buffer.

Returns:

the number of bytes actually read or -1 if end of stream.

Throws:

IOException - If an IOException occurs.

skip

public long skip(long count)
          throws IOException

Skips count number of bytes in this PushbackInputStream. Subsequent read()'s will not return these bytes unless reset() is used. This implementation skips count number of bytes in the buffer and/or the target stream.

Overrides:

skip in class FilterInputStream

Parameters:

count - the number of bytes to skip.

Returns:

the number of bytes actually skipped.

Throws:

IOException - If the stream is already closed or another IOException occurs.

unread

public void unread(byte[] buffer)
            throws IOException

Push back all the bytes in buffer. The bytes are pushed so that they would be read back buffer[0], buffer[1], etc. If the push back buffer cannot handle the entire contents of buffer, an IOException will be thrown. Some of the buffer may already be in the buffer after the exception is thrown.

Parameters:

buffer - the byte array containing bytes to push back into the stream.

Throws:

IOException - If the pushback buffer becomes, or is, full.

unread

public void unread(byte[] buffer,
                   int offset,
                   int length)
            throws IOException

Push back length number of bytes in buffer starting at offset. The bytes are pushed so that they would be read back buffer[offset], buffer[offset+1], etc. If the push back buffer cannot handle the bytes copied from buffer, an IOException will be thrown. Some of the bytes may already be in the buffer after the exception is thrown.

Parameters:

buffer - the byte array containing bytes to push back into the stream.

offset - the location to start taking bytes to push back.

length - the number of bytes to push back.

Throws:

IOException - If the pushback buffer becomes, or is, full.

unread

public void unread(int oneByte)
            throws IOException

Push back one byte. Takes the byte oneByte and puts in in the local buffer of bytes to read back before accessing the target input stream.

Parameters:

oneByte - the byte to push back into the stream.

Throws:

IOException - If the pushback buffer is already full.

mark

public void mark(int readlimit)

Make a mark of the current position in the stream but the mark method does nothing.

Overrides:

mark in class FilterInputStream

Parameters:

readlimit - the maximum number of bytes that are able to be read before the mark becomes invalid

reset

public void reset()
           throws IOException

Reset current position to the mark made previously int the stream, but the reset method will throw IOException and do nothing else if called.

Overrides:

reset in class FilterInputStream

Throws:

IOException - If the method is called