Top Description Fields Constructors Methods
liquibase.io

public Class WriterOutputStream

extends OutputStream
Class Inheritance
Imports
java.io.IOException, .OutputStream, .Writer, java.nio.ByteBuffer, .CharBuffer, java.nio.charset.Charset, .CharsetDecoder, .CoderResult, .CodingErrorAction
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 java.io.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 java.io.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 java.io.InputStreamReader, except that the control flow is reversed: both classes transform a byte stream into a character stream, but java.io.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

Field Summary

Modifier and TypeField and Description
private static final int
BUFFER_SIZE

private final CharsetDecoder
decoder

private final ByteBuffer
decoderIn

ByteBuffer used as input for the decoder.

private final CharBuffer
decoderOut

CharBuffer used as output for the decoder.

private final boolean
writeImmediately

private final Writer
writer

Constructor Summary

AccessConstructor and Description
public
WriterOutputStream(final Writer
the target 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.

public
WriterOutputStream(final Writer
the target Writer
writer, final Charset
the charset encoding
charset)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.

public
WriterOutputStream(final Writer
the target Writer
writer, final Charset
the charset encoding
charset, final int
the size of the output buffer in number of characters
bufferSize, final boolean
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.
writeImmediately)

Constructs a new WriterOutputStream.

public
WriterOutputStream(final Writer
the target Writer
writer, final CharsetDecoder
the charset decoder
decoder)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.

public
WriterOutputStream(final Writer
the target Writer
writer, final CharsetDecoder
the charset decoder
decoder, final int
the size of the output buffer in number of characters
bufferSize, final boolean
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.
writeImmediately)

Constructs a new WriterOutputStream.

public
WriterOutputStream(final Writer
the target Writer
writer, final String
the name of the charset encoding
charsetName)

Constructs a new WriterOutputStream with a default output buffer size of 1024 characters.

public
WriterOutputStream(final Writer
the target Writer
writer, final String
the name of the charset encoding
charsetName, final int
the size of the output buffer in number of characters
bufferSize, final boolean
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.
writeImmediately)

Constructs a new WriterOutputStream.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Close the stream.

public void
flush()

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Flush the stream.

private void
flushOutput()

Flush the output.

private void
processInput(final boolean
indicates end of input
endOfInput)

Decode the contents of the input ByteBuffer into a CharBuffer.

public void
write(final byte[]
the byte array containing the bytes to write
b)

Overrides java.io.OutputStream.write.

Write bytes from the specified byte array to the stream.

public void
write(final byte[]
the byte array containing the bytes to write
b, int
the start offset in the byte array
off, int
the number of bytes to write
len)

Overrides java.io.OutputStream.write.

Write bytes from the specified byte array to the stream.

public void
write(final int
the byte to write
b)

Implements abstract java.io.OutputStream.write.

Write a single byte to the stream.

Inherited from java.io.OutputStream:
nullOutputStream

Field Detail

BUFFER_SIZEback to summary
private static final int BUFFER_SIZE
decoderback to summary
private final CharsetDecoder decoder
decoderInback to summary
private final 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.

decoderOutback to summary
private final CharBuffer decoderOut

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

writeImmediatelyback to summary
private final boolean writeImmediately
writerback to summary
private final Writer writer

Constructor Detail

WriterOutputStreamback to summary
public WriterOutputStream(final 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:Writer

the target Writer

Annotations
@Deprecated
WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final 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:Writer

the target Writer

charset:Charset

the charset encoding

WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final Charset charset, final int bufferSize, final boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters
writer:Writer

the target Writer

charset:Charset

the charset encoding

bufferSize:int

the size of the output buffer in number of characters

writeImmediately:boolean

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.

WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final 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:Writer

the target Writer

decoder:CharsetDecoder

the charset decoder

Since
2.1
WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final CharsetDecoder decoder, final int bufferSize, final boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters
writer:Writer

the target Writer

decoder:CharsetDecoder

the charset decoder

bufferSize:int

the size of the output buffer in number of characters

writeImmediately:boolean

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
WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final 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:Writer

the target Writer

charsetName:String

the name of the charset encoding

WriterOutputStreamback to summary
public WriterOutputStream(final Writer writer, final String charsetName, final int bufferSize, final boolean writeImmediately)

Constructs a new WriterOutputStream.

Parameters
writer:Writer

the target Writer

charsetName:String

the name of the charset encoding

bufferSize:int

the size of the output buffer in number of characters

writeImmediately:boolean

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.

Method Detail

closeback to summary
public void close() throws IOException

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

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.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.
flushback to summary
public void flush() throws IOException

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

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.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.
flushOutputback to summary
private void flushOutput() throws IOException

Flush the output.

Exceptions
IOException:
if an I/O error occurs.
processInputback to summary
private void processInput(final boolean endOfInput) throws IOException

Decode the contents of the input ByteBuffer into a CharBuffer.

Parameters
endOfInput:boolean

indicates end of input

Exceptions
IOException:
if an I/O error occurs.
writeback to summary
public void write(final byte[] b) throws IOException

Overrides java.io.OutputStream.write.

Write bytes from the specified byte array to the stream.

Parameters
b:byte[]

the byte array containing the bytes to write

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.
writeback to summary
public void write(final byte[] b, int off, int len) throws IOException

Overrides java.io.OutputStream.write.

Write bytes from the specified byte array to the stream.

Parameters
b:byte[]

the byte array containing the bytes to write

off:int

the start offset in the byte array

len:int

the number of bytes to write

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.
writeback to summary
public void write(final int b) throws IOException

Implements abstract java.io.OutputStream.write.

Write a single byte to the stream.

Parameters
b:int

the byte to write

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.