com.massa.util.io

Class AdvancedReader

java.lang.Object

com.massa.util.io.AdvancedReader

All Implemented Interfaces:

Closeable, AutoCloseable, Readable

public class AdvancedReader
extends Object
implements Readable, Closeable

A character-stream reader that allows one or more characters to be unread.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AdvancedReader.CommentHandler Called by read method to allow comment handling.

Field Summary

Fields

Modifier and Type	Field and Description
protected Reader	in The underlying character-input stream.
protected Object	lock

Constructor Summary

Constructors

Constructor and Description
AdvancedReader(Reader in) Create a new pushback reader with a 512 characters pushback buffer.
AdvancedReader(Reader in, int size) Create a new pushback reader with a pushback buffer of the given size.

Method Summary

Modifier and Type	Method and Description
void	clear(int n) Clear n characters that can be unread (the oldest ones).
void	clearAll() Clear all characters that can be unread.
void	clearLast(int n) Clear n characters that can be unread (the newer ones).
void	close() Close the stream.
int	countToMark(int mark) Counts characters between current position and specified mark.
int	getAtMark(int mark)
int	getColumnNumber()
int	getColumnNumberAtMark(int mark)
AdvancedReader.CommentHandler	getCommentHandler() Retrieves comment handler
int	getLineNumber()
int	getLineNumberAtMark(int mark)
int	getMaxReadLen() Maximum number of characters to read from underlying reader
boolean	isAtEnd() Tells if there is no more charater to read from this reader.
boolean	isAtMark(int startMark)
void	mark(int readAheadLimit) Mark the present position in the stream.
boolean	markSupported() Tell whether this stream supports the mark() operation, which it does not.
int	putMark() Puts an internal mark in order to be able to return to the current stream position.
int	read() Read a single character.
int	read(char[] cbuf) Read characters into an array.
int	read(char[] cbuf, int off, int len) Read characters into a portion of an array.
int	read(CharBuffer target) Attempts to read characters into the specified character buffer.
int	readFromCache() Read a single character, but will not access the underlying reader.
char[]	readFromMark(int mark) Reads from specified mark until current position.
boolean	readUntil(Appendable builder, CharDetector endDetector) Reads source into builder until end char is detected or EOF is encountered.
char[]	readUntilMark(int mark) Reads from current position until specified mark.
boolean	ready() Tell whether this stream is ready to be read.
void	reset() Reset the stream.
boolean	returnToMark(int mark) Returns to the position marked by this mark ID.
void	setCommentHandler(AdvancedReader.CommentHandler commentHandler) Specifies a comment handler
void	setMaxReadLen(int maxReadLen) Specifies maximum number of characters to read from underlying reader
long	skip(long n) Skip characters, which are not possible to unread.
long	skip(long n, boolean keep) Skip characters.
int	unread() Unread one character and return it.
void	unread(int n) Unreads n characters.
void	unreadAll() Unread all characters since last clear.
boolean	unreadUntil(StringBuilder builder, CharDetector endDetector) Reads source into builder until end char is detected or SOF (Start Of File) is encountered.

Methods inherited from class java.lang.Object

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

Field Detail

lock

protected Object lock

in

protected Reader in

The underlying character-input stream.

Constructor Detail

AdvancedReader

public AdvancedReader(Reader in,
                      int size)

Create a new pushback reader with a pushback buffer of the given size.

Parameters:

in - The reader from which characters will be read

size - The size of the pushback buffer

Throws:

IllegalArgumentException - if size is <= 0

AdvancedReader

public AdvancedReader(Reader in)

Create a new pushback reader with a 512 characters pushback buffer.

Parameters:

in - The reader from which characters will be read

Method Detail

putMark

public int putMark()
            throws IOException

Puts an internal mark in order to be able to return to the current stream position.
The mark id is guaranteed to be greater than zero.

Returns:

Mark ID

Throws:

IOException - Because in some cases, the next character must be read from underlying reader.

isAtMark

public boolean isAtMark(int startMark)

returnToMark

public boolean returnToMark(int mark)

Returns to the position marked by this mark ID.

Parameters:

mark - Mark ID

Returns:

true if mark found.

countToMark

public int countToMark(int mark)

Counts characters between current position and specified mark.

Parameters:

mark - Mark ID

Returns:

-1 if mark not found.

readFromMark

public char[] readFromMark(int mark)

Reads from specified mark until current position. If mark equals current, returns empty array. If mark does not exist or is after current, returns null.

Parameters:

mark - Mark ID

Returns:

true if mark found.

readUntilMark

public char[] readUntilMark(int mark)

Reads from current position until specified mark. If mark equals current, returns empty array. If mark does not exist or is before current, returns null.

Parameters:

mark - Mark ID

Returns:

true if mark found.

readFromCache

public int readFromCache()
                  throws IOException

Read a single character, but will not access the underlying reader.
Meaning that this method can only return a value different from -1 if an unread has been performed.

Returns:

The character read, or -1 if the end of the cached stream has been reached

Throws:

IOException - If an I/O error occurs

read

public int read()
         throws IOException

Read a single character.

Returns:

The character read, or -1 if the end of the stream has been reached

Throws:

IOException - If an I/O error occurs

read

public int read(CharBuffer target)
         throws IOException

Attempts to read characters into the specified character buffer. The buffer is used as a repository of characters as-is: the only changes made are the results of a put operation. No flipping or rewinding of the buffer is performed.

Specified by:

read in interface Readable

Parameters:

target - the buffer to read characters into

Returns:

The number of characters added to the buffer, or -1 if this source of characters is at its end

Throws:

IOException - if an I/O error occurs

NullPointerException - if target is null

ReadOnlyBufferException - if target is a read only buffer

read

public int read(char[] cbuf)
         throws IOException

Read characters into an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Parameters:

cbuf - Destination buffer

Returns:

The number of characters read, or -1 if the end of the stream has been reached

Throws:

IOException - If an I/O error occurs

read

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

Read characters into a portion of an array.

Parameters:

cbuf - Destination buffer

off - Offset at which to start writing characters

len - Maximum number of characters to read

Returns:

The number of characters read, or -1 if the end of the stream has been reached

Throws:

IOException - If an I/O error occurs

isAtEnd

public boolean isAtEnd()
                throws IOException

Tells if there is no more charater to read from this reader.

Throws:

IOException

unread

public int unread()
           throws IOException

Unread one character and return it. If back to start of source, return -1.

Throws:

IOException

unread

public void unread(int n)
            throws IOException

Unreads n characters.

Parameters:

n - The number of characters to unread

Throws:

IOException - If I/O error occurs

unreadAll

public void unreadAll()
               throws IOException

Unread all characters since last clear.

Throws:

IOException - If I/O error occurs

clear

public void clear(int n)
           throws IOException

Clear n characters that can be unread (the oldest ones).

Parameters:

n - The number of characters to clear

Throws:

IOException - If I/O error occurs

clearLast

public void clearLast(int n)
               throws IOException

Clear n characters that can be unread (the newer ones).

Parameters:

n - The number of characters to clear

Throws:

IOException - If I/O error occurs

clearAll

public void clearAll()
              throws IOException

Clear all characters that can be unread.

Throws:

IOException - If I/O error occurs

ready

public boolean ready()
              throws IOException

Tell whether this stream is ready to be read.

Throws:

IOException - If an I/O error occurs

mark

public void mark(int readAheadLimit)
          throws IOException

Mark the present position in the stream. The mark for class AdvancedReader always throws an exception.

Throws:

IOException - Always, since mark is not supported

reset

public void reset()
           throws IOException

Reset the stream. The reset method of AdvancedReader always throws an exception.

Throws:

IOException - Always, since reset is not supported

markSupported

public boolean markSupported()

Tell whether this stream supports the mark() operation, which it does not.

close

public void close()
           throws IOException

Close the stream.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - If an I/O error occurs

skip

public long skip(long n)
          throws IOException

Skip characters, which are not possible to unread.

Parameters:

n - The number of characters to skip

Returns:

The number of characters actually skipped

Throws:

IllegalArgumentException - If n is negative.

IOException - If an I/O error occurs

skip

public long skip(long n,
                 boolean keep)
          throws IOException

Skip characters.

Parameters:

n - The number of characters to skip

keep - Tells if the characters should be available for unread

Returns:

The number of characters actually skipped

Throws:

IllegalArgumentException - If n is negative.

IOException - If an I/O error occurs

getLineNumber

public int getLineNumber()

Returns:

Line number at current position

getColumnNumber

public int getColumnNumber()

Returns:

Column number at current position

getAtMark

public int getAtMark(int mark)

Returns:

Stream value at position pointed by provided mark

getLineNumberAtMark

public int getLineNumberAtMark(int mark)

Returns:

Line number at position pointed by provided mark

getColumnNumberAtMark

public int getColumnNumberAtMark(int mark)

Returns:

Line number at position pointed by provided mark

readUntil

public boolean readUntil(Appendable builder,
                         CharDetector endDetector)
                  throws IOException

Reads source into builder until end char is detected or EOF is encountered.
Ending char is NOT unread from source.

Returns:

true if end char is detected (false if EOF is encountered)

Throws:

IOException

unreadUntil

public boolean unreadUntil(StringBuilder builder,
                           CharDetector endDetector)
                    throws IOException

Reads source into builder until end char is detected or SOF (Start Of File) is encountered.
Ending char is NOT reread from source.

Returns:

true if end char is detected (false if SOF is encountered)

Throws:

IOException

getCommentHandler

public AdvancedReader.CommentHandler getCommentHandler()

Retrieves comment handler

setCommentHandler

public void setCommentHandler(AdvancedReader.CommentHandler commentHandler)

Specifies a comment handler

getMaxReadLen

public int getMaxReadLen()

Maximum number of characters to read from underlying reader

setMaxReadLen

public void setMaxReadLen(int maxReadLen)

Specifies maximum number of characters to read from underlying reader