javolution.io

Class UTF8StreamReader

java.lang.Object

java.io.Reader

javolution.io.UTF8StreamReader

All Implemented Interfaces:

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

public final class UTF8StreamReader
extends java.io.Reader
implements Reusable

This class represents a UTF-8 stream reader.

This reader supports surrogate char pairs (representing characters in the range [U+10000 .. U+10FFFF]). It can also be used to read characters unicodes (31 bits) directly (ref. read()).

Each invocation of one of the read() methods may cause one or more bytes to be read from the underlying byte-input stream. To enable the efficient conversion of bytes to characters, more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation.

Instances of this class can be reused for different input streams and can be part of a higher level component (e.g. parser) in order to avoid dynamic buffer allocation when the input source changes. Also wrapping using a java.io.BufferedReader is unnescessary as instances of this class embed their own data buffers.

Note: This reader is unsynchronized and does not test if the UTF-8 encoding is well-formed (e.g. UTF-8 sequences longer than necessary to encode a character).

Version:

2.0, December 9, 2004

Author:

Jean-Marie Dautelle

See Also:

UTF8StreamWriter

Field Summary

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

Constructor and Description
UTF8StreamReader() Creates a UTF-8 reader having a byte buffer of moderate capacity (2048).
UTF8StreamReader(int capacity) Creates a UTF-8 reader having a byte buffer of specified capacity.

Method Summary

Modifier and Type	Method and Description
void	close() Closes and resets this reader for reuse.
int	read() Reads a single character.
void	read(java.lang.Appendable dest) Reads characters into the specified appendable.
int	read(char[] cbuf, int off, int len) Reads characters into a portion of an array.
boolean	ready() Indicates if this stream is ready to be read.
void	reset() Resets the internal state of this object to its default values.
UTF8StreamReader	setInput(java.io.InputStream inStream) Sets the input stream to use for reading until this reader is closed.
UTF8StreamReader	setInputStream(java.io.InputStream inStream) Deprecated. Replaced by setInput(InputStream)

Methods inherited from class java.io.Reader

mark, markSupported, read, read, skip

Methods inherited from class java.lang.Object

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

Constructor Detail

UTF8StreamReader

public UTF8StreamReader()

Creates a UTF-8 reader having a byte buffer of moderate capacity (2048).

UTF8StreamReader

public UTF8StreamReader(int capacity)

Creates a UTF-8 reader having a byte buffer of specified capacity.

Parameters:

capacity - the capacity of the byte buffer.

Method Detail

setInput

public UTF8StreamReader setInput(java.io.InputStream inStream)

Sets the input stream to use for reading until this reader is closed. For example:

     Reader reader = new UTF8StreamReader().setInput(inStream);
 

is equivalent but reads twice as fast as

     Reader reader = new java.io.InputStreamReader(inStream, "UTF-8");
 

Parameters:

inStream - the input stream.

Returns:

this UTF-8 reader.

Throws:

java.lang.IllegalStateException - if this reader is being reused and it has not been closed or reset.

ready

public boolean ready()
              throws java.io.IOException

Indicates if this stream is ready to be read.

Overrides:

ready in class java.io.Reader

Returns:

true if the next read() is guaranteed not to block for input; false otherwise.

Throws:

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

close

public void close()
           throws java.io.IOException

Closes and resets this reader for reuse.

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 - if an I/O error occurs.

read

public int read()
         throws java.io.IOException

Reads a single character. This method will block until a character is available, an I/O error occurs or the end of the stream is reached.

Overrides:

read in class java.io.Reader

Returns:

the 31-bits Unicode of the character read, or -1 if the end of the stream has been reached.

Throws:

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

read

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

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

Note: Characters between U+10000 and U+10FFFF are represented by surrogate pairs (two char).

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

Returns:

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

Throws:

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

read

public void read(java.lang.Appendable dest)
          throws java.io.IOException

Reads characters into the specified appendable. This method will block until the end of the stream is reached.

Parameters:

dest - the destination buffer.

Throws:

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

reset

public void reset()

Description copied from interface: Reusable

Resets the internal state of this object to its default values.

Specified by:

reset in interface Reusable

Overrides:

reset in class java.io.Reader

setInputStream

@Deprecated
public UTF8StreamReader setInputStream(java.io.InputStream inStream)

Deprecated. Replaced by setInput(InputStream)