Contents | Prev | Next | Index

22.13 The Class java.io.PushbackInputStream

A 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. 

public class PushbackInputStream extends FilterInputStream {
	protected int	 pushBack = -1;
	public PushbackInputStream(InputStream in);
	public int read() throws IOException;
	public int read(byte[] bytes, int offset, int length)
		throws IOException, NullPointerException,
			IndexOutOfBoundsException;
	public void unread(int ch) throws IOException;
	public int available() throws IOException;
	public boolean markSupported();
}

22.13.1 protected int pushBack = -1;

If this field has a nonnegative value, it is a byte that was pushed back. If this field is -1, there is currently no pushed-back byte.

22.13.2 public PushbackInputStream(InputStream in)

This constructor initializes a newly created PushbackInputStream by saving its argument, the input stream in, for later use. Initially, there is no pushed-back byte (the field pushBack is initialized to -1).

22.13.3 public int read() throws IOException

See the general contract of the read method of InputStream (§22.3.1).

If pushBack is not -1, the value of pushBack is returned and pushBack is set to -1. Otherwise, a byte is obtained from the contained input stream.

Overrides the read method of FilterInputStream (§22.9.3).

22.13.4 public int read(byte[] bytes, int offset, int length) throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the read method of InputStream (§22.3.3).

If pushBack is not -1, it is used as an input byte (and pushBack is set to -1) before any bytes are read from the contained input stream.

Overrides the read method of FilterInputStream (§22.9.5).

22.13.5 public void unread(int b) throws IOException

If pushBack is not -1, an IOException is thrown (it is not permitted to push back more than one byte). Otherwise, the byte value b is pushed back by assigning b to pushBack.

22.13.6 public int available() throws IOException

See the general contract of the available method of InputStream (§22.3.1).

This method first calls the available method of the contained input stream. If pushBack is -1, the result is returned; otherwise, the result plus 1 is returned.

Overrides the available method of FilterInputStream (§22.9.7).

22.13.7 public boolean markSupported()

This method returns false (a PushbackInputStream does not support mark).

Contents | Prev | Next | Index

Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to doug.kramer@sun.com