lava.io
Class MarkReader

java.lang.Object
  |
  +--java.io.Reader
        |
        +--java.io.FilterReader
              |
              +--lava.io.LFilterReader
                    |
                    +--lava.io.MarkReader

public final class MarkReader

extends LFilterReader

Adds mark support to Reader.

Details: Currently, the only java.io classes that support the mark, reset, and readLine methods are BufferedReader and its descendants. MarkReader is designed to give you a choice -- to enable you to use mark and reset without requiring you to use a BufferedReader. MarkReader allows you to add mark and reset capabilities to any Reader.

Example: Suppose you want to read user input from the console, and occasionally mark the stream while doing so (so that you can go back and reread some portions). With the current java.io package, the only way you can do this is to create a BufferedReader.

However, if you do this, blocking may occur where blocking shouldn't occur. This is because BufferedReader tries to completely refill the read buffer -- even, for example, if a carriage return has already been encountered midway through the fill. Imagine the user's frustration when he is prompted to enter a line of text: He enters it, pushes return, and sees that nothing will happen until he enters additional lines of text -- text for which he has not yet received the prompts -- just so that he can fill the buffer enough to make the call to readLine return!

This serious problem has been reported as a bug in Java 1.1, and this class is a perfect workaround for it. Now you can use mark and still avoid the BufferedReader bug that causes this problem.

Fields inherited from class java.io.FilterReader

in

Fields inherited from class java.io.Reader

lock

Constructor Summary

MarkReader(java.io.Reader reader)
Initializes a new MarkReader to read from the indicated Reader.

Method Summary

static java.io.Reader	adapt(java.io.Reader reader) Returns a Reader, based on the supplied reader, that is guaranteed to have mark capabilities.
void	mark(int read_ahead_limit) Mark the present position in this filtered stream.
boolean	markSupported() Indicates that this Reader supports marking.
int	read() Reads the next character from the stream.
int	read(char[] dest, int off, int len) Reads a block of characters from the stream.
void	reset() Attempts to reset the stream.

Methods inherited from class lava.io.LFilterReader

read

Methods inherited from class java.io.FilterReader

close, ready, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

MarkReader

public MarkReader(java.io.Reader reader)

Initializes a new MarkReader to read from the indicated Reader.

Parameters:

reader - the reader that this MarkReader will read from

Method Detail

adapt

public static java.io.Reader adapt(java.io.Reader reader)

Returns a Reader, based on the supplied reader, that is guaranteed to have mark capabilities. If the supplied reader supports mark already, it will simply be returned. Otherwise, the supplied reader will be embedded into a new instance of MarkReader, and the new MarkReader will be returned.

Parameters:

reader - the reader to adapt

Returns:

a read that supports mark

read

public int read()
         throws java.io.IOException

Reads the next character from the stream.

Overrides:

read in class java.io.FilterReader

Returns:

the character read

read

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

Reads a block of characters from the stream.

Overrides:

read in class java.io.FilterReader

Parameters:

dest - destination array for storing characters read

off - starting offset into the destination array

len - number of characters to read

Returns:

number of characters actually read (may be lest than len, indicating EOF or IO trouble)

Throws:

java.io.IOException - if an I/O error occurs

mark

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

Mark the present position in this filtered stream. Subsequent calls to reset() will attempt to reposition the stream to state it was at when this method was called. There is a limit on how many characters can be read ahead before attempts to reset are no longer guaranteed to succeed.

Overrides:

mark in class java.io.FilterReader

Parameters:

read_ahead_limit - the read ahead limit

reset

public void reset()
           throws java.io.IOException

Attempts to reset the stream. If the stream has been marked, then this method will attempt to store the state of the stream at the time it was marked. If the stream has not been marked, then this method will attempt to reset the stream in some way that is appropriate to this particular stream.

Overrides:

reset in class java.io.FilterReader

Throws:

java.io.IOException - if the stream cannot be reset

markSupported

public boolean markSupported()

Indicates that this Reader supports marking.

Overrides:

markSupported in class java.io.FilterReader

Returns:

true