java.io

Class PushbackReader

java.lang.Object

java.io.Reader

java.io.FilterReader

java.io.PushbackReader

All Implemented Interfaces:

Closeable, AutoCloseable, Readable

public class PushbackReader
extends FilterReader

Wraps an existing Reader and adds functionality to "push back" characters that have been read, so that they can be read again. Parsers may find this useful. The number of characters which may be pushed back can be specified during construction. If the buffer of pushed back bytes is empty, characters are read from the underlying reader.

Field Summary

Fields inherited from class java.io.FilterReader

in

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
PushbackReader(Reader in) Constructs a new PushbackReader with the specified reader as source.
PushbackReader(Reader in, int size) Constructs a new PushbackReader with in as source reader.

Method Summary

Modifier and Type	Method and Description
void	close() Closes this reader.
void	mark(int readAheadLimit) Marks the current position in this stream.
boolean	markSupported() Indicates whether this reader supports the mark(int) and reset() methods.
int	read() Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0.
int	read(char[] buffer, int offset, int count) Reads up to count characters from this reader and stores them in character array buffer starting at offset.
boolean	ready() Indicates whether this reader is ready to be read without blocking.
void	reset() Resets this reader to the last marked position.
long	skip(long charCount) Skips charCount characters in this reader.
void	unread(char[] buffer) Pushes all the characters in buffer back to this reader.
void	unread(char[] buffer, int offset, int length) Pushes a subset of the characters in buffer back to this reader.
void	unread(int oneChar) Pushes the specified character oneChar back to this reader.

Methods inherited from class java.io.Reader

nullReader, read, read, transferTo

Methods inherited from class java.lang.Object

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

Constructor Detail

PushbackReader

public PushbackReader(Reader in)

Constructs a new PushbackReader with the specified reader as source. The size of the pushback buffer is set to the default value of 1 character.

Parameters:

in - the source reader.

PushbackReader

public PushbackReader(Reader in,
                      int size)

Constructs a new PushbackReader with in as source reader. The size of the pushback buffer is set to size.

Parameters:

in - the source reader.

size - the size of the pushback buffer.

Throws:

IllegalArgumentException - if size is negative.

Method Detail

close

public void close()
           throws IOException

Closes this reader. This implementation closes the source reader and releases the pushback buffer.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class FilterReader

Throws:

IOException - if an error occurs while closing this reader.

mark

public void mark(int readAheadLimit)
          throws IOException

Marks the current position in this stream. Setting a mark is not supported in this class; this implementation always throws an IOException.

Overrides:

mark in class FilterReader

Parameters:

readAheadLimit - the number of character that can be read from this reader before the mark is invalidated; this parameter is ignored.

Throws:

IOException - if this method is called.

See Also:

FilterReader.markSupported(), FilterReader.reset()

markSupported

public boolean markSupported()

Indicates whether this reader supports the mark(int) and reset() methods. PushbackReader does not support them, so it returns false.

Overrides:

markSupported in class FilterReader

Returns:

always false.

See Also:

mark(int), reset()

read

public int read()
         throws IOException

Reads a single character from this reader and returns it as an integer with the two higher-order bytes set to 0. Returns -1 if the end of the reader has been reached. If the pushback buffer does not contain any available characters then a character from the source reader is returned. Blocks until one character has been read, the end of the source reader is detected or an exception is thrown.

Overrides:

read in class FilterReader

Returns:

the character read or -1 if the end of the source reader has been reached.

Throws:

IOException - if this reader is closed or an I/O error occurs while reading from this reader.

read

public int read(char[] buffer,
                int offset,
                int count)
         throws IOException

Reads up to count characters from this reader and stores them in character array buffer starting at offset. Characters are read from the pushback buffer first, then from the source reader if more bytes are required. Blocks until count characters have been read, the end of the source reader is detected or an exception is thrown. Returns the number of bytes read or -1 if the end of the source reader has been reached.

Overrides:

read in class FilterReader

Throws:

IndexOutOfBoundsException - if offset < 0 || count < 0 || offset + count > buffer.length.

IOException - if this reader is closed or another I/O error occurs while reading from this reader.

ready

public boolean ready()
              throws IOException

Indicates whether this reader is ready to be read without blocking. Returns true if this reader will not block when read is called, false if unknown or blocking will occur.

Overrides:

ready in class FilterReader

Returns:

true if the receiver will not block when read() is called, false if unknown or blocking will occur.

Throws:

IOException - if this reader is closed or some other I/O error occurs.

See Also:

read(), read(char[], int, int)

reset

public void reset()
           throws IOException

Resets this reader to the last marked position. Resetting the reader is not supported in this class; this implementation always throws an IOException.

Overrides:

reset in class FilterReader

Throws:

IOException - if this method is called.

See Also:

FilterReader.mark(int), FilterReader.markSupported()

unread

public void unread(char[] buffer)
            throws IOException

Pushes all the characters in buffer back to this reader. The characters are pushed back in such a way that the next character read from this reader is buffer[0], then buffer[1] and so on.

If this reader's internal pushback buffer cannot store the entire contents of buffer, an IOException is thrown. Parts of buffer may have already been copied to the pushback buffer when the exception is thrown.

Parameters:

buffer - the buffer containing the characters to push back to this reader.

Throws:

IOException - if this reader is closed or the free space in the internal pushback buffer is not sufficient to store the contents of buffer.

unread

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

Pushes a subset of the characters in buffer back to this reader. The subset is defined by the start position offset within buffer and the number of characters specified by length. The bytes are pushed back in such a way that the next byte read from this stream is buffer[offset], then buffer[1] and so on.

If this stream's internal pushback buffer cannot store the selected subset of buffer, an IOException is thrown. Parts of buffer may have already been copied to the pushback buffer when the exception is thrown.

Parameters:

buffer - the buffer containing the characters to push back to this reader.

offset - the index of the first byte in buffer to push back.

length - the number of bytes to push back.

Throws:

IndexOutOfBoundsException - if offset < 0 or count < 0, or if offset + count is greater than the length of buffer.

IOException - if this reader is closed or the free space in the internal pushback buffer is not sufficient to store the selected contents of buffer.

NullPointerException - if buffer is null.

unread

public void unread(int oneChar)
            throws IOException

Pushes the specified character oneChar back to this reader. This is done in such a way that the next character read from this reader is (char) oneChar.

If this reader's internal pushback buffer cannot store the character, an IOException is thrown.

Parameters:

oneChar - the character to push back to this stream.

Throws:

IOException - if this reader is closed or the internal pushback buffer is full.

skip

public long skip(long charCount)
          throws IOException

Skips charCount characters in this reader. This implementation skips characters in the pushback buffer first and then in the source reader if necessary.

Overrides:

skip in class FilterReader

Returns:

the number of characters actually skipped.

Throws:

IllegalArgumentException - if charCount < 0.

IOException - if this reader is closed or another I/O error occurs.

See Also:

FilterReader.mark(int), FilterReader.markSupported(), FilterReader.reset()