Package org.apache.commons.io.output

Class WriterOutputStream

java.lang.Object

java.io.OutputStream

org.apache.commons.io.output.WriterOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

public class WriterOutputStream
extends java.io.OutputStream

OutputStream implementation that transforms a byte stream to a character stream using a specified charset encoding and writes the resulting stream to a Writer. The stream is transformed using a CharsetDecoder object, guaranteeing that all charset encodings supported by the JRE are handled correctly.

The output of the CharsetDecoder is buffered using a fixed size buffer. This implies that the data is written to the underlying Writer in chunks that are no larger than the size of this buffer. By default, the buffer is flushed only when it overflows or when flush() or close() is called. In general there is therefore no need to wrap the underlying Writer in a BufferedWriter. WriterOutputStream can also be instructed to flush the buffer after each write operation. In this case, all available data is written immediately to the underlying Writer, implying that the current position of the Writer is correlated to the current position of the WriterOutputStream.

WriterOutputStream implements the inverse transformation of OutputStreamWriter; in the following example, writing to out2 would have the same result as writing to out directly (provided that the byte sequence is legal with respect to the charset encoding):

 OutputStream out = ...
 Charset cs = ...
 OutputStreamWriter writer = new OutputStreamWriter(out, cs);
 WriterOutputStream out2 = new WriterOutputStream(writer, cs);

WriterOutputStream implements the same transformation as InputStreamReader, except that the control flow is reversed: both classes transform a byte stream into a character stream, but InputStreamReader pulls data from the underlying stream, while WriterOutputStream pushes it to the underlying stream.

Note that while there are use cases where there is no alternative to using this class, very often the need to use this class is an indication of a flaw in the design of the code. This class is typically used in situations where an existing API only accepts an OutputStream object, but where the stream is known to represent character data that must be decoded for further use.

Instances of WriterOutputStream are not thread safe.

Since:

2.0

See Also:

ReaderInputStream

Field Summary

Fields

Modifier and Type	Field	Description
private static int	BUFFER_SIZE
private java.nio.charset.CharsetDecoder	decoder
private java.nio.ByteBuffer	decoderIn	ByteBuffer used as input for the decoder.
private java.nio.CharBuffer	decoderOut	CharBuffer used as output for the decoder.
private boolean	writeImmediately
private java.io.Writer	writer

Constructor Summary

Constructors

Constructor	Description
WriterOutputStream(java.io.Writer writer)	Deprecated. 2.5 use WriterOutputStream(Writer, Charset) instead
WriterOutputStream(java.io.Writer writer, java.lang.String charsetName)	Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.
WriterOutputStream(java.io.Writer writer, java.lang.String charsetName, int bufferSize, boolean writeImmediately)	Constructs a new WriterOutputStream.
WriterOutputStream(java.io.Writer writer, java.nio.charset.Charset charset)	Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.
WriterOutputStream(java.io.Writer writer, java.nio.charset.CharsetDecoder decoder)	Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.
WriterOutputStream(java.io.Writer writer, java.nio.charset.CharsetDecoder decoder, int bufferSize, boolean writeImmediately)	Constructs a new WriterOutputStream.
WriterOutputStream(java.io.Writer writer, java.nio.charset.Charset charset, int bufferSize, boolean writeImmediately)	Constructs a new WriterOutputStream.

Method Summary

Modifier and Type	Method	Description
private static void	checkIbmJdkWithBrokenUTF16(java.nio.charset.Charset charset)	Check if the JDK in use properly supports the given charset.
void	close()	Close the stream.
void	flush()	Flush the stream.
private void	flushOutput()	Flush the output.
private void	processInput(boolean endOfInput)	Decode the contents of the input ByteBuffer into a CharBuffer.
void	write(byte[] b)	Write bytes from the specified byte array to the stream.
void	write(byte[] b, int off, int len)	Write bytes from the specified byte array to the stream.
void	write(int b)	Write a single byte to the stream.

Methods inherited from class java.io.OutputStream

nullOutputStream

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE

private static final int BUFFER_SIZE

See Also:

Constant Field Values

writer

private final java.io.Writer writer

decoder

private final java.nio.charset.CharsetDecoder decoder

writeImmediately

private final boolean writeImmediately

decoderIn

private final java.nio.ByteBuffer decoderIn

ByteBuffer used as input for the decoder. This buffer can be small as it is used only to transfer the received data to the decoder.

decoderOut

private final java.nio.CharBuffer decoderOut

CharBuffer used as output for the decoder. It should be somewhat larger as we write from this buffer to the underlying Writer.

Constructor Detail

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.nio.charset.CharsetDecoder decoder)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.

Parameters:

writer - the target Writer

decoder - the charset decoder

Since:

2.1

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.nio.charset.CharsetDecoder decoder,
                          int bufferSize,
                          boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters:

writer - the target Writer

decoder - the charset decoder

bufferSize - the size of the output buffer in number of characters

writeImmediately - If true the output buffer will be flushed after each write operation, i.e. all available data will be written to the underlying Writer immediately. If false, the output buffer will only be flushed when it overflows or when flush() or close() is called.

Since:

2.1

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.nio.charset.Charset charset,
                          int bufferSize,
                          boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters:

writer - the target Writer

charset - the charset encoding

bufferSize - the size of the output buffer in number of characters

writeImmediately - If true the output buffer will be flushed after each write operation, i.e. all available data will be written to the underlying Writer immediately. If false, the output buffer will only be flushed when it overflows or when flush() or close() is called.

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.nio.charset.Charset charset)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.

Parameters:

writer - the target Writer

charset - the charset encoding

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.lang.String charsetName,
                          int bufferSize,
                          boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters:

writer - the target Writer

charsetName - the name of the charset encoding

bufferSize - the size of the output buffer in number of characters

writeImmediately - If true the output buffer will be flushed after each write operation, i.e. all available data will be written to the underlying Writer immediately. If false, the output buffer will only be flushed when it overflows or when flush() or close() is called.

WriterOutputStream

public WriterOutputStream(java.io.Writer writer,
                          java.lang.String charsetName)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.

Parameters:

writer - the target Writer

charsetName - the name of the charset encoding

WriterOutputStream

@Deprecated
public WriterOutputStream(java.io.Writer writer)

Deprecated.

2.5 use WriterOutputStream(Writer, Charset) instead

Constructs a new WriterOutputStream that uses the default character encoding and with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.

Parameters:

writer - the target Writer

Method Detail

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Write bytes from the specified byte array to the stream.

Overrides:

write in class java.io.OutputStream

Parameters:

b - the byte array containing the bytes to write

off - the start offset in the byte array

len - the number of bytes to write

Throws:

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

write

public void write(byte[] b)
           throws java.io.IOException

Write bytes from the specified byte array to the stream.

Overrides:

write in class java.io.OutputStream

Parameters:

b - the byte array containing the bytes to write

Throws:

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

write

public void write(int b)
           throws java.io.IOException

Write a single byte to the stream.

Specified by:

write in class java.io.OutputStream

Parameters:

b - the byte to write

Throws:

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

flush

public void flush()
           throws java.io.IOException

Flush the stream. Any remaining content accumulated in the output buffer will be written to the underlying Writer. After that Writer.flush() will be called.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

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

close

public void close()
           throws java.io.IOException

Close the stream. Any remaining content accumulated in the output buffer will be written to the underlying Writer. After that Writer.close() will be called.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.OutputStream

Throws:

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

processInput

private void processInput(boolean endOfInput)
                   throws java.io.IOException

Decode the contents of the input ByteBuffer into a CharBuffer.

Parameters:

endOfInput - indicates end of input

Throws:

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

flushOutput

private void flushOutput()
                  throws java.io.IOException

Flush the output.

Throws:

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

checkIbmJdkWithBrokenUTF16

private static void checkIbmJdkWithBrokenUTF16(java.nio.charset.Charset charset)

Check if the JDK in use properly supports the given charset.

Parameters:

charset - the charset to check the support for