tribble.io
Class StackedReader

java.lang.Object
  java.io.Reader
      tribble.io.StackedReader

All Implemented Interfaces:

java.io.Closeable, java.lang.Readable

public class StackedReader
extends java.io.Reader

Push-down stack of input reader streams. Manages a stack of Reader objects.

This is useful for implementing readers for source files that contain nested inclusions of other source files (a la the #include directive of C and C++).

Each file inclusion is achieved by pushing the included file as a new reader onto the reader stack. Subsequent input is then read from the reader on the top of the stack. Once the end of the input of that reader is reached, the reader is automatically closed and popped from the stack, and subsequent input is read from the previously pushed reader that is now the new top of the stack. Once all of the reader streams have been popped, the end of the entire stream is reached and no more input is available.

Source code:

http://david.tribble.com/src/java/tribble/io/StackedReader.java

Documentation:

http://david.tribble.com/docs/tribble/io/StackedReader.html

Since:

2008-09-27

Version:

$Revision: 1.2 $ $Date: 2008/09/27 18:04:14 $

Author:

David R. Tribble (david@tribble.com)

Copyright ©2008 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by by the United States Department of State as a terrorist, or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

Field Summary

static int	END_OF_FILE Special code indicating end-of-file (-2).
static int	END_OF_INPUT Special code indicating end of the input stream (-1).
(package private) static java.lang.String	REV

Fields inherited from class java.io.Reader

lock

Constructor Summary

StackedReader()
Constructor.

StackedReader(java.io.Reader in)
Constructor.

StackedReader(java.io.Reader in, boolean eof)
Constructor.

StackedReader(java.io.Reader in, java.lang.Object lock)
Constructor.

StackedReader(java.io.Reader in, java.lang.Object lock, boolean eof)
Constructor.

Method Summary

void	close() Close the input stream and all of the currently saved (pushed) input streams in the stack.
java.io.Reader	getInput() Retrieve the current input stream from the stack of readers.
boolean	isClosed() Determine if the input stream is closed.
void	mark(int readAheadLimit) This operation is not supported.
boolean	markSupported() Determine whether the stream supports the mark() operation (which it does not).
void	popInput() Close the current input stream and remove (pop) it from the stack of readers, restoring the previously saved (pushed) stream.
void	pushInput(java.io.Reader in) Insert (push) an input stream onto the stack of readers.
int	read() Read a character from the current input stream.
int	read(char[] cbuf, int off, int len) Read characters from the current input stream.
boolean	ready() Determine if the stream is ready to be read.
void	reset() This operation is not supported.

Methods inherited from class java.io.Reader

read, read, skip

Methods inherited from class java.lang.Object

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

Field Detail

REV

static final java.lang.String REV

See Also:

Constant Field Values

END_OF_INPUT

public static final int END_OF_INPUT

Special code indicating end of the input stream (-1).

See Also:

Constant Field Values

END_OF_FILE

public static final int END_OF_FILE

Special code indicating end-of-file (-2).

See Also:

Constant Field Values

Constructor Detail

StackedReader

public StackedReader()

Constructor. Equivalent to:

    new StackedReader(null, null, false);

The internal stack of reader streams is empty until method pushInput() is called.

Since:

1.1, 2008-09-26

StackedReader

public StackedReader(java.io.Reader in)

Constructor. Equivalent to:

    new StackedReader(in, null, false);

Since:

1.1, 2008-09-26

StackedReader

public StackedReader(java.io.Reader in,
                     boolean eof)

Constructor. Equivalent to:

    new StackedReader(in, null, eof);

Since:

1.1, 2008-09-26

StackedReader

public StackedReader(java.io.Reader in,
                     java.lang.Object lock)

Constructor. Equivalent to:

    new StackedReader(in, lock, false);

Since:

1.1, 2008-09-27

StackedReader

public StackedReader(java.io.Reader in,
                     java.lang.Object lock,
                     boolean eof)

Constructor.

Parameters:

in - Reader input stream.

lock - An object used to synchronize critical operations on the reader. This can be null, in which case critical sections will synchronize on the reader object itself.

eof - If true, the end of each reader stream is indicated by a special END_OF_FILE character code. If false, the end of each stream is not indicated in any way, but is simply discarded.

Throws:

java.lang.NullPointerException - (unchecked) Thrown if in is null.

Since:

1.1, 2008-09-27

Method Detail

getInput

public java.io.Reader getInput()

Retrieve the current input stream from the stack of readers.

Returns:

The current input stream being read from, or null if there is none.

Since:

1.1, 2008-09-26

pushInput

public void pushInput(java.io.Reader in)

Insert (push) an input stream onto the stack of readers. This saves (pushes) the current input stream, suspends reading from it, and establishes a new input stream as the current input reader. Subsequent reads will read characters from the new input stream.

Once the end of the current input stream is reached, it will be closed, and the previously saved input stream is restored (popped) from the internal stack, and reading resumes from it.

Parameters:

in - Input stream.

Throws:

java.lang.NullPointerException - (unchecked) Thrown if in is null.

Since:

1.1, 2008-09-26

popInput

public void popInput()
              throws java.io.IOException

Close the current input stream and remove (pop) it from the stack of readers, restoring the previously saved (pushed) stream.

Under normal operating conditions, this method never needs to be called by client classes.

Throws:

java.io.IOException - Thrown if an error occurs while attemping to close the input stream.

Since:

1.1, 2008-09-26

close

public void close()
           throws java.io.IOException

Close the input stream and all of the currently saved (pushed) input streams in the stack. The input streams are closed in the reverse order in which they were pushed onto the stack.

Specified by:

close in interface java.io.Closeable

Specified by:

close in class java.io.Reader

Throws:

java.io.IOException - Thrown if an error occurs while attemping to close any of the input streams. Only the first exception thrown is re-thrown by this method, any others are ignored.

Since:

1.1, 2008-09-26

isClosed

public boolean isClosed()

Determine if the input stream is closed.

Returns:

True if the end of the input reader stack has been reached, or if there are no more input streams to read from.

Since:

1.1, 2008-09-26

read

public int read()
         throws java.io.IOException

Read a character from the current input stream.

Note that this method is not synchronized.

Overrides:

read in class java.io.Reader

Returns:

A Unicode character code in the range [0x0000,0xFFFF], or END_OF_INPUT if the end of the entire input stream has been reached. If the end of the current reader in the stack of readers is reached, and the eof parameter was true when the input stream was created, the special code END_OF_FILE is returned; if eof was false, the reader stream is closed and a character is read from the previously saved (pushed) input stream, and no indication that the end of an individual input stream was reached is returned.

Throws:

java.io.IOException - Thrown if an I/O (read) error occurs.

Since:

1.1, 2008-09-26

read

public int read(char[] cbuf,
                int off,
                int len)
         throws java.io.IOException

Read characters from the current input stream.

Note that this method is not synchronized.

Specified by:

read in class java.io.Reader

Parameters:

cbuf - Character buffer to read into.

off - Index of the first character in cbuf to read.

len - Number of characters to read into cbuf

Returns:

The number of characters read from the input stream stack, or END_OF_INPUT if the end of the entire input stream has been reached and there are no more characters to read. If the end of the current reader in the stack of readers is reached, and the eof parameter was true when the input stream was created, cbuf is filled with the characters read up to the end of the stream, and the next read will return the special code END_OF_FILE; subsequent reads after that will read from the previously saved (pushed) input stream. If eof was false, the file is closed and characters are then read from the previously saved (pushed) input stream, and no indication that the end of an individual input stream was reached is returned.

Throws:

java.io.IOException - Thrown if an I/O (read) error occurs.

Since:

1.1, 2008-09-26

ready

public boolean ready()
              throws java.io.IOException

Determine if the stream is ready to be read.

Overrides:

ready in class java.io.Reader

Returns:

True if the next call to read() is guaranteed not to block for input, otherwise false. Note that returning false does not guarantee that the next read will block.

Throws:

java.io.IOException - Thrown if an I/O (read) error occurs.

Since:

1.1, 2008-09-26

markSupported

public boolean markSupported()

Determine whether the stream supports the mark() operation (which it does not).

Overrides:

markSupported in class java.io.Reader

Returns:

False, always.

Since:

1.1, 2008-09-26

mark

public void mark(int readAheadLimit)
          throws java.io.IOException

This operation is not supported.

Overrides:

mark in class java.io.Reader

Throws:

java.io.IOException - Always thrown.

Since:

1.1, 2008-09-26

reset

public void reset()
           throws java.io.IOException

This operation is not supported.

Overrides:

reset in class java.io.Reader

Throws:

java.io.IOException - Always thrown.

Since:

1.1, 2008-09-26