tribble.io
Class StackedReader

java.lang.Object
  extended by java.io.Reader
      extended by 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