org.apache.commons.io.output

Class WriterOutputStream

java.lang.Object

java.io.OutputStream

org.apache.commons.io.output.WriterOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class WriterOutputStream
extends 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):

To build an instance, use WriterOutputStream.Builder.

 OutputStream out = ...
 Charset cs = ...
 OutputStreamWriter writer = new OutputStreamWriter(out, cs);
 WriterOutputStream out2 = WriterOutputStream.builder()
   .setWriter(writer)
   .setCharset(cs)
   .get();
 

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.

See Also:

WriterOutputStream.Builder, ReaderInputStream

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WriterOutputStream.Builder Builds a new WriterOutputStream.

Field Summary

Fields

Modifier and Type	Field and Description
static int	BUFFER_SIZE

Method Summary

Modifier and Type	Method and Description
static WriterOutputStream.Builder	builder() Constructs a new WriterOutputStream.Builder.
void	close() Close the stream.
void	flush() Flush the stream.
void	write(byte[] b) Writes bytes from the specified byte array to the stream.
void	write(byte[] b, int off, int len) Writes bytes from the specified byte array to the stream.
void	write(int b) Writes a single byte to the stream.

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE

See Also:

Constant Field Values

Method Detail

builder

public static WriterOutputStream.Builder builder()

Constructs a new WriterOutputStream.Builder.

Returns:

a new WriterOutputStream.Builder.

close

public void close()
           throws 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 Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class OutputStream

Throws:

IOException - if an I/O error occurs.

flush

public void flush()
           throws 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 Flushable

Overrides:

flush in class OutputStream

Throws:

IOException - if an I/O error occurs.

write

public void write(byte[] b)
           throws IOException

Writes bytes from the specified byte array to the stream.

Overrides:

write in class OutputStream

Parameters:

b - the byte array containing the bytes to write

Throws:

IOException - if an I/O error occurs.

write

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

Writes bytes from the specified byte array to the stream.

Overrides:

write in class 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:

IOException - if an I/O error occurs.

write

public void write(int b)
           throws IOException

Writes a single byte to the stream.

Specified by:

write in class OutputStream

Parameters:

b - the byte to write

Throws:

IOException - if an I/O error occurs.