info.bioinfweb.commons.io

Class PeekReader

java.lang.Object

java.io.Reader

info.bioinfweb.commons.io.PeekReader

All Implemented Interfaces:

StreamLocationProvider, java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable

public class PeekReader
extends java.io.Reader
implements StreamLocationProvider

Reader implementation that allows to peek upcoming characters from the underlying reader. A specified number of characters a precached into a buffer from the underlying reader to keep then available for peek operations.

Since:

1.2.0

Author:

Ben Stöver

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PeekReader.ReadResult Stores information about the result of a read operation, as it is returned by some methods of PeekReader.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_PEEK_BUFFER_SIZE

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
PeekReader(java.io.Reader underlyingReader) Creates a new instance of this class with the default peek buffer size (DEFAULT_PEEK_BUFFER_SIZE) and fills the initial peek buffer.
PeekReader(java.io.Reader underlyingReader, int peekLength) Creates a new instance of this class and fills the initial peek buffer.

Method Summary

Modifier and Type	Method and Description
void	close()
int	consumeNewLine() Consumes any one of a line feed '\n', a carriage return '\r', or a carriage return followed immediately by a line feed, if found at the current position of the reader.
int	getAvailablePeek() Returns the number of characters that can be previewed in front of the current position in the stream.
long	getCharacterOffset() Returns the number of characters that have been read from this reader since the beginning of the underlying stream.
long	getColumnNumber() Returns the column of the current line, where the cursor of this reader is currently located.
long	getLineNumber() Returns the number of the line in the stream, where the cursor of this reader is currently located.
boolean	isNewLineNext() Tests of the character that will be returned by the next call of e.g.
boolean	isNext(java.lang.String sequence) Tests of the specified string is contained in the underlying character stream at the current position.
boolean	isNext(java.lang.String[] sequences) Tests if one of the specified strings is contained in the underlying character stream at the current position.
boolean	markSupported()
int	peek() Returns integer representation of the character at the current position of this reader without moving forward in the stream.
int	peek(char[] cbuf)
int	peek(char[] cbuf, int off, int len) Copies the specified number of positions from the peek buffer to the specified array.
int	peek(int offset) Returns the integer representation of the character that would be returned after offset calls of Reader.read().
char	peekChar() Returns the character at the current position of this reader without moving forward in the stream.
char	peekChar(int offset) Returns the character that would be returned after offset calls of Reader.read().
PeekReader.ReadResult	peekLine()
java.lang.String	peekString(int length) Previews the specified number of characters and returns them as a string.
int	read(char[] cbuf, int off, int len) Copies the specified number of characters into the specified array.
char	readChar() Reads the next character.
PeekReader.ReadResult	readLine() Reads a line of text.
PeekReader.ReadResult	readLine(int maxLength) Reads a line of text with the specified maximum length.
PeekReader.ReadResult	readRegExp(int maxLength, java.util.regex.Pattern pattern, boolean greedy) Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached or the maximum number of characters was read.
PeekReader.ReadResult	readRegExp(int maxLength, java.lang.String regExp, boolean greedy) Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached or the maximum number of characters was read.
PeekReader.ReadResult	readRegExp(java.util.regex.Pattern pattern, boolean greedy) Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached.
PeekReader.ReadResult	readRegExp(java.lang.String regExp, boolean greedy) Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached.
java.lang.String	readString(int length) Reads the specified number of characters and returns them as a string.
PeekReader.ReadResult	readUntil(int maxLength, java.lang.String terminationSequence) Reads characters into a string buffer until the specified termination sequence is found or the end of the stream is reached.
PeekReader.ReadResult	readUntil(int maxLength, java.lang.String[] terminationSequences)
protected PeekReader.ReadResult	readUntil(int maxLength, java.lang.String[] terminationSequences, boolean untilWhitespace)
PeekReader.ReadResult	readUntil(java.lang.String terminationSequence) Reads characters into a string buffer until the specified termination sequence is found.
PeekReader.ReadResult	readUntil(java.lang.String[] terminationSequences)
PeekReader.ReadResult	readUntilWhitespace(int maxLength, java.lang.String terminationSequence)
PeekReader.ReadResult	readUntilWhitespace(int maxLength, java.lang.String[] terminationSequences)
PeekReader.ReadResult	readUntilWhitespace(java.lang.String[] terminationSequences)
void	reset()
int	whichIsNext(java.lang.String[] sequences) Determines which of the specified strings is located at the current position of this reader.

Methods inherited from class java.io.Reader

mark, read, read, read, ready, skip

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PEEK_BUFFER_SIZE

public static final int DEFAULT_PEEK_BUFFER_SIZE

See Also:

Constant Field Values

Constructor Detail

PeekReader

public PeekReader(java.io.Reader underlyingReader,
                  int peekLength)
           throws java.io.IOException

Creates a new instance of this class and fills the initial peek buffer.

Parameters:

underlyingReader - the reader to read the data from

peekLength - the number of characters to keep available for peek operations in in front of the actual reader position

Throws:

java.io.IOException - if an I/O exception occurs while filling the initial peek buffer

PeekReader

public PeekReader(java.io.Reader underlyingReader)
           throws java.io.IOException

Creates a new instance of this class with the default peek buffer size (DEFAULT_PEEK_BUFFER_SIZE) and fills the initial peek buffer.

Parameters:

underlyingReader - the reader to read the data from

Throws:

java.io.IOException - if an I/O exception occurs while filling the initial peek buffer

Method Detail

getCharacterOffset

public long getCharacterOffset()

Returns the number of characters that have been read from this reader since the beginning of the underlying stream.

Note that due to the buffering of this class, this value may differ from the number of characters that have been read from the underlying stream.

Specified by:

getCharacterOffset in interface StreamLocationProvider

Returns:

the number of characters that have currently been read from this reader instance

getLineNumber

public long getLineNumber()

Returns the number of the line in the stream, where the cursor of this reader is currently located.

This reader keeps track of the line number by monitoring each line separator that is read. Supported line separators are '\n', '\r' or '\r\n'.

Specified by:

getLineNumber in interface StreamLocationProvider

Returns:

the current line number

getColumnNumber

public long getColumnNumber()

Returns the column of the current line, where the cursor of this reader is currently located.

Specified by:

getColumnNumber in interface StreamLocationProvider

Returns:

the current column number in the current line

See Also:

getLineNumber()

getAvailablePeek

public int getAvailablePeek()

Returns the number of characters that can be previewed in front of the current position in the stream.

The return value will be equal to the buffer size specified in the constructor unless the end of the underlying stream is enclosed.

Returns:

the number of currently buffered characters

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in class java.io.Reader

Throws:

java.io.IOException

markSupported

public boolean markSupported()

Overrides:

markSupported in class java.io.Reader

reset

public void reset()
           throws java.io.IOException

Overrides:

reset in class java.io.Reader

Throws:

java.io.IOException

peek

public int peek(char[] cbuf)

peek

public int peek(char[] cbuf,
                int off,
                int len)

Copies the specified number of positions from the peek buffer to the specified array. If more characters are requested than are contained in the buffer, all characters in the buffer are copied.

Parameters:

cbuf - the array to copy the buffer contents to

off - the target offset in cbuf

len - the maximum number of characters that shall be copied

Returns:

the number of characters that have been copied (This will never be greater than len or the current buffer content length.)

peekString

public java.lang.String peekString(int length)

Previews the specified number of characters and returns them as a string. If the end of the stream is reached before the specified number of characters have been read, the returned string will be shorter than length.

Parameters:

length - the number of characters to preview

Returns:

the characters that would be read next as a string

readString

public java.lang.String readString(int length)
                            throws java.io.IOException

Reads the specified number of characters and returns them as a string. If the end of the stream is reached before the specified number of characters have been read, the returned string will be shorter than length.

Parameters:

length - the number of characters to read

Returns:

the read characters as a string

Throws:

java.io.IOException - if an I/O error occurs during the read operation

read

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

Copies the specified number of characters into the specified array. The characters are taken from the peek buffer (and additional characters are copied from the underlying reader if necessary) and the peek buffer is refilled by data read from the underlying reader, if possible.

Specified by:

read in class java.io.Reader

Parameters:

cbuf - the destination buffer

off - the offset at which to start storing characters

len - the maximum number of characters to read

Throws:

java.io.IOException

readChar

public char readChar()
              throws java.io.IOException

Reads the next character.

Returns:

the next character

Throws:

java.io.IOException - if there are no more characters to read (the end of the stream has been reached)

peekChar

public char peekChar()
              throws java.io.EOFException

Returns the character at the current position of this reader without moving forward in the stream.

Returns:

the next character

Throws:

java.io.EOFException - if the end of the stream was already reached

peek

public int peek()

Returns integer representation of the character at the current position of this reader without moving forward in the stream.

Returns:

the integer representation of next the character or -1 if the end of the stream has been reached

peekChar

public char peekChar(int offset)
              throws java.lang.IndexOutOfBoundsException,
                     java.io.EOFException

Returns the character that would be returned after offset calls of Reader.read().

Parameters:

offset - the index of the character relative to the current reader position (The character at the current position (that would be returned by the next call of Reader.read()) would have the index 0.)

Returns:

the peeked character

Throws:

java.lang.IndexOutOfBoundsException - if the specified index lies further away from the current reader position than the number of precached characters allows

java.io.EOFException - if this reader already knows that the specified offset lies behind the end of the underlying stream. (This is only possible for offsets below the buffer size, specified in the constructor.)

See Also:

getAvailablePeek()

peek

public int peek(int offset)
         throws java.lang.IndexOutOfBoundsException

Returns the integer representation of the character that would be returned after offset calls of Reader.read().

Parameters:

offset - the index of the character relative to the current reader position (The character at the current position (that would be returned by the next call of Reader.read()) would have the index 0.)

Returns:

the integer representation of the character at the specified offset or -1 if this reader already knows that the specified offset lies behind the end of the underlying stream. (This is only possible for offsets below the buffer size, specified in the constructor.)

Throws:

java.lang.IndexOutOfBoundsException - if the specified index lies further away from the current reader position than the number of precached characters allows

See Also:

getAvailablePeek()

peekLine

public PeekReader.ReadResult peekLine()

isNewLineNext

public boolean isNewLineNext()

Tests of the character that will be returned by the next call of e.g. Reader.read() will be a new line character (\n or (\r).

Returns:

true if the next character will be a new line character or false if it will be some other character or the end of the underlying stream has been reached.

isNext

public boolean isNext(java.lang.String sequence)
               throws java.lang.IllegalArgumentException

Tests of the specified string is contained in the underlying character stream at the current position.

Parameters:

sequence - the string to search for

Returns:

true if the specified string is found, false otherwise

Throws:

java.lang.IllegalArgumentException - if the specified string is longer than the peek length

isNext

public boolean isNext(java.lang.String[] sequences)
               throws java.lang.IllegalArgumentException

Tests if one of the specified strings is contained in the underlying character stream at the current position.

Parameters:

sequences - the strings to search for

Returns:

true if one of the specified strings is found, false otherwise

Throws:

java.lang.IllegalArgumentException - if one of the specified strings is longer than the peek length

whichIsNext

public int whichIsNext(java.lang.String[] sequences)
                throws java.lang.IllegalArgumentException

Determines which of the specified strings is located at the current position of this reader.

Parameters:

sequences - the strings to check for

Returns:

the index of the string in sequences that was found or -1 if none of the strings was found

Throws:

java.lang.IllegalArgumentException - if one of the specified strings is longer than the peek length

consumeNewLine

public int consumeNewLine()
                   throws java.io.IOException

Consumes any one of a line feed '\n', a carriage return '\r', or a carriage return followed immediately by a line feed, if found at the current position of the reader.

Returns:

the number of characters that have been consumed by this method (0 - 2)

Throws:

java.io.IOException - if an I/O error occurs during the read operation

readLine

public PeekReader.ReadResult readLine()
                               throws java.io.IOException

Reads a line of text. A line is considered to be terminated by any one of a line feed '\n', a carriage return '\r', or a carriage return followed immediately by a line feed.

The terminating new line characters are consumed from the underlying reader by this method although they are not contained in the returned value.

Returns:

the line of text not including the terminal new line character(s)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readLine

public PeekReader.ReadResult readLine(int maxLength)
                               throws java.io.IOException

Reads a line of text with the specified maximum length. A line is considered to be terminated by any one of a line feed '\n', a carriage return '\r', or a carriage return followed immediately by a line feed.

If terminating new line characters are reached, they are consumed from the underlying reader by this method although they are not contained in the returned value.

Parameters:

maxLength - the maximum length the returned line may have

Returns:

a line of text with the specified length or shorter if a new character or the end of the stream were found earlier (Does not include the terminal new line character(s).)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readUntil

public PeekReader.ReadResult readUntil(java.lang.String terminationSequence)
                                throws java.io.IOException

Reads characters into a string buffer until the specified termination sequence is found.

The returned result does not contain the termination sequence, although these characters have been consumed.

Parameters:

terminationSequence - a string specifying the termination sequence

Returns:

the character sequence read from the underlying stream not containing the specified termination sequence

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readUntil

public PeekReader.ReadResult readUntil(int maxLength,
                                       java.lang.String terminationSequence)
                                throws java.io.IOException

Reads characters into a string buffer until the specified termination sequence is found or the end of the stream is reached.

The returned result does not contain the termination sequence, if it was found, although these characters have been consumed.

Parameters:

maxLength - the maximum length the read sequence (not including the termination sequence) may have

terminationSequence - a string specifying the termination sequence

Returns:

the character sequence read from the underlying stream

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

java.lang.IllegalArgumentException - if the terminationSequence is longer than maxLength or longer than the available peek length

readUntilWhitespace

public PeekReader.ReadResult readUntilWhitespace(int maxLength,
                                                 java.lang.String terminationSequence)
                                          throws java.io.IOException

Throws:

java.io.IOException

readUntil

public PeekReader.ReadResult readUntil(java.lang.String[] terminationSequences)
                                throws java.io.IOException

Throws:

java.io.IOException

readUntilWhitespace

public PeekReader.ReadResult readUntilWhitespace(java.lang.String[] terminationSequences)
                                          throws java.io.IOException

Throws:

java.io.IOException

readUntil

public PeekReader.ReadResult readUntil(int maxLength,
                                       java.lang.String[] terminationSequences)
                                throws java.io.IOException

Throws:

java.io.IOException

readUntilWhitespace

public PeekReader.ReadResult readUntilWhitespace(int maxLength,
                                                 java.lang.String[] terminationSequences)
                                          throws java.io.IOException

Throws:

java.io.IOException

readUntil

protected PeekReader.ReadResult readUntil(int maxLength,
                                          java.lang.String[] terminationSequences,
                                          boolean untilWhitespace)
                                   throws java.io.IOException

Throws:

java.io.IOException

readRegExp

public PeekReader.ReadResult readRegExp(java.lang.String regExp,
                                        boolean greedy)
                                 throws java.io.IOException

Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached.

This method is useful to read strings that can be separated by different character patterns. To e.g. allow all white spaces as separators the following call could be made: readRagExp(100, ".+\\s+").

Note that in contrast to readLine(int) or readUntil(int, String) no defined termination sequence will be removed from the returned result, because the whole result is matched against the specified pattern.

Parameters:

regExp - the regular expression defining how the returned sequence should look like

greedy - Specify true here if the longest possible sequence matching the pattern shall be read or false if the algorithms should stop already when the shortest possible matching sequence was found.

Returns:

a character sequence matching the specified pattern (or the end of the stream is reached if the pattern could not be matched before)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readRegExp

public PeekReader.ReadResult readRegExp(int maxLength,
                                        java.lang.String regExp,
                                        boolean greedy)
                                 throws java.io.IOException

Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached or the maximum number of characters was read.

This method is useful to read strings that can be separated by different character patterns. To e.g. allow all white spaces as separators the following call could be made: readRagExp(100, ".+\\s+").

Note that in contrast to readLine(int) or readUntil(int, String) no defined termination sequence will be removed from the returned result, because the whole result is matched against the specified pattern.

Parameters:

maxLength - the maximum length the returned sequence may have

regExp - the regular expression defining how the returned sequence should look like

greedy - Specify true here if the longest possible sequence (considering maxLength) matching the pattern shall be read or false if the algorithms should stop already when the shortest possible matching sequence was found.

Returns:

a character sequence matching the specified pattern (or the characters from the current position until maxLength or the end of the stream is reached if the pattern could not be matched before)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readRegExp

public PeekReader.ReadResult readRegExp(java.util.regex.Pattern pattern,
                                        boolean greedy)
                                 throws java.io.IOException

Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached.

This method is useful to read strings that can be separated by different character patterns. To e.g. allow all white spaces as separators the following call could be made: readRagExp(100, ".+\\s+").

Note that in contrast to readLine(int) or readUntil(int, String) no defined termination sequence will be removed from the returned result, because the whole result is matched against the specified pattern.

Parameters:

pattern - the regular expression pattern defining how the returned sequence should look like

greedy - Specify true here if the longest possible sequence matching the pattern shall be read or false if the algorithms should stop already when the shortest possible matching sequence was found.

Returns:

a character sequence matching the specified pattern (or the end of the stream is reached if the pattern could not be matched before)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream

readRegExp

public PeekReader.ReadResult readRegExp(int maxLength,
                                        java.util.regex.Pattern pattern,
                                        boolean greedy)
                                 throws java.io.IOException

Reads characters into a string buffer until the contents of this buffer match the specified pattern or the end of the stream is reached or the maximum number of characters was read.

This method is useful to read strings that can be separated by different character patterns. To e.g. allow all white spaces as separators the following call could be made: readRagExp(100, ".+\\s+").

Note that in contrast to readLine(int) or readUntil(int, String) no defined termination sequence will be removed from the returned result, because the whole result is matched against the specified pattern.

Parameters:

maxLength - the maximum length the read sequence may have

pattern - the regular expression pattern defining how the returned sequence should look like

greedy - Specify true here if the longest possible sequence (considering maxLength) matching the pattern shall be read or false if the algorithms should stop already when the shortest possible matching sequence was found.

Returns:

a character sequence matching the specified pattern (or the characters from the current position until maxLength or the end of the stream is reached if the pattern could not be matched before)

Throws:

java.io.IOException - if an I/O exception occurs while reading from the underlying stream