Chapter 11
The java.io Package

PushbackInputStream

Name

PushbackInputStream

Synopsis

Class Name:

java.io.PushbackInputStream

Superclass:

java.io.FilterInputStream

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

JDK 1.0 or later

The PushbackInputStream class represents a byte stream that allows data to be pushed back into the stream. In other words, after data has been read from a PushbackInputStream, it can be pushed back into the stream so that it can be reread. This functionality is useful for implementing things like parsers that need to read data and then return it to the input stream.

The PushbackInputStream has been enhanced as of JDK 1.1 to support a pushback buffer that is larger than one byte. Prior to JDK 1.1, the class supported only a one-byte buffer using the protected variable pushBack. As of 1.1, that variable has been replaced by the buf and pos variables.

Class Summary

public class java.io.PushbackInputStream extends java.io.FilterInputStream {
  // Variables
  protected byte[] buf;                           // New in 1.1
  protected int pos;                              // New in 1.1
  // Constructors
  public PushbackInputStream(InputStream in);
  public PushbackInputStream(InputStream in, 
                             int size);           // New in 1.1
  // Instance Methods
  public int available(); 
  public boolean markSupported();
  public int read();
  public int read(byte[] b, int off, int len);
  public void unread(int b);
  public void unread(byte[] b);                   // New in 1.1
  public void unread(byte[] b, int off, int len); // New in 1.1
}

Variables

buf

protected byte[] buf

Availability

New as of JDK 1.1

Description

The buffer that holds data that has been pushed back.

pos

protected int pos

Availability

New as of JDK 1.1

Description

The position of pushed-back data in the buffer. When there is no pushed-back data, pos is buf.length. As data is pushed back, pos decreases. As pushed-back data is read, pos increases. When the pushback buffer is full, pos is 0.

Constructors

PushbackInputStream

public PushbackInputStream(InputStream in)

Parameters

in: The input stream to wrap.

Description

This constructor creates a PushbackInputStream that reads from the given InputStream, using a pushback buffer with the default size of one byte.

public PushBackInputStream(InputStream in, int size)

Availability

New as of JDK 1.1

Parameters

in

The input stream to wrap.

size

The size of the pushback buffer.

Description

This constructor creates a PushbackInputStream that reads from the given InputStream, using a pushback buffer of the given size.

Instance Methods

available

public int available() throws IOException

Returns

The number of bytes that can be read without blocking.

Throws

IOException: If any kind of I/O error occurs.

Overrides

FilterInputStream.available()

Description

This method returns the number of bytes that can be read without having to wait for more data to become available. This is b + u, where b is the number of bytes in the pushback buffer and u is the number of available bytes in the underlying stream.

markSupported

public boolean markSupported()

Returns

The boolean value false.

Overrides

FilterInputStream.markSupported()

Description

This method returns false to indicate that this class does not support mark() and reset().

read

public int read() throws IOException

Returns

The next byte of data, or -1 if the end of the stream is encountered.

Throws

IOException: If any kind of I/O error occurs.

Overrides

FilterInputStream.read()

Description

This method reads a byte of data. If there is any data in the pushback buffer, the method returns the next byte in the pushback buffer. Otherwise, it calls the read() method of the underlying stream. The method blocks until the byte is read, the end of the stream is encountered, or an exception is thrown.

public int read(byte b[], int off, int len) throws IOException

Parameters

b

An array of bytes to be filled from the stream.

off

An offset into the byte array.

len

The number of bytes to read.

Returns

The actual number of bytes read, or -1 if the end of the stream is encountered immediately.

Throws

IOException: If any kind of I/O error occurs.

Overrides

FilterInputStream.read(byte[], int, int)

Description

This method copies bytes from the stream into the given array b, starting at index off and continuing for len bytes. If the array can be populated solely from the pushback buffer, the method returns immediately. Otherwise, the read(byte[], int, int) method of the underlying stream is called to make up the difference. The method blocks until some data is available.

unread

public void unread(int b) throws IOException

Parameters

b: The value to push back.

Throws

IOException: If the pushback buffer is full.

Description

This method puts the given byte into the pushback buffer.

public void unread(byte[] b) throws IOException

Availability

New as of JDK 1.1

Parameters

b: An array of bytes to push back.

Throws

IOException: If the pushback buffer is full.

Description

This method puts all of the bytes in the given array into the pushback buffer.

public void unread(byte[] b, int off, int len) throws IOException

Availability

New as of JDK 1.1

Parameters

b

An array of bytes to push back.

off

An offset into the array.

len

The number of bytes to push back.

Throws

IOException: If the pushback buffer is full.

Description

This method puts len bytes from the given array, starting at offset off, into the pushback buffer.

Inherited Methods

Method	Inherited From	Method	Inherited From
`clone()`	`Object`	`close()`	`FilterInputStream`
`equals(Object)`	`Object`	`finalize()`	`Object`
`getClass()`	`Object`	`hashCode()`	`Object`
`mark(int)`	`FilterInputStream`	`notify()`	`Object`
`notifyAll()`	`Object`	`read(byte[])`	`FilterInputStream`
`reset()`	`FilterInputStream`	`skip(long)`	`FilterInputStream`
`toString()`	`Object`	`wait()`	`Object`
`wait(long)`	`Object`	`wait(long, int)`	`Object`