javolution.io

Class UTF8StreamWriter

java.lang.Object

java.io.Writer

javolution.io.UTF8StreamWriter

All Implemented Interfaces:

Closeable, Flushable, Appendable, AutoCloseable

public final class UTF8StreamWriter
extends Writer

A UTF-8 stream writer.

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

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

Note: This writer is unsynchronized and always produces well-formed UTF-8 sequences.

Version:

2.0, December 9, 2004

Author:

Jean-Marie Dautelle

Field Summary

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes and resets this writer for reuse.
void	flush() Flushes the stream.
void	reset()
UTF8StreamWriter	setOutput(OutputStream out) Sets the output stream to use for writing until this writer is closed.
UTF8StreamWriter	setOutputStream(OutputStream out) Deprecated. Replaced by setOutput(OutputStream)
void	write(char c) Writes a single character.
void	write(char[] cbuf, int off, int len) Writes a portion of an array of characters.
void	write(CharSequence csq) Writes the specified character sequence.
void	write(int code) Writes a character given its 31-bits Unicode.
void	write(String str, int off, int len) Writes a portion of a string.

Methods inherited from class java.io.Writer

append, append, append, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

UTF8StreamWriter

public UTF8StreamWriter()

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

UTF8StreamWriter

public UTF8StreamWriter(int capacity)

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

Parameters:

capacity - the capacity of the byte buffer.

Method Detail

setOutput

public UTF8StreamWriter setOutput(OutputStream out)

Sets the output stream to use for writing until this writer is closed. For example:

     Writer writer = new UTF8StreamWriter().setOutputStream(out);
 

is equivalent but writes faster than

     Writer writer = new java.io.OutputStreamWriter(out, "UTF-8");
 

Parameters:

out - the output stream.

Returns:

this UTF-8 writer.

Throws:

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

write

public void write(char c)
           throws IOException

Writes a single character. This method supports 16-bits character surrogates.

Parameters:

c - char the character to be written (possibly a surrogate).

Throws:

IOException - if an I/O error occurs.

write

public void write(int code)
           throws IOException

Writes a character given its 31-bits Unicode.

Overrides:

write in class Writer

Parameters:

code - the 31 bits Unicode of the character to be written.

Throws:

IOException - if an I/O error occurs.

write

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

Writes a portion of an array of characters.

Specified by:

write in class Writer

Parameters:

cbuf - the array of characters.

off - the offset from which to start writing characters.

len - the number of characters to write.

Throws:

IOException - if an I/O error occurs.

write

public void write(String str,
         int off,
         int len)
           throws IOException

Writes a portion of a string.

Overrides:

write in class Writer

Parameters:

str - a String.

off - the offset from which to start writing characters.

len - the number of characters to write.

Throws:

IOException - if an I/O error occurs

write

public void write(CharSequence csq)
           throws IOException

Writes the specified character sequence.

Parameters:

csq - the character sequence.

Throws:

IOException - if an I/O error occurs

flush

public void flush()
           throws IOException

Flushes the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams.

Specified by:

flush in interface Flushable

Specified by:

flush in class Writer

Throws:

IOException - if an I/O error occurs.

close

public void close()
           throws IOException

Closes and resets this writer for reuse.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in class Writer

Throws:

IOException - if an I/O error occurs

reset

public void reset()

setOutputStream

public UTF8StreamWriter setOutputStream(OutputStream out)

Deprecated. Replaced by setOutput(OutputStream)