Class WriterOutputStream

java.lang.Object
java.io.OutputStream
com.carrotsearch.randomizedtesting.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): 

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

  • Field Details

    • DEFAULT_BUFFER_SIZE

      private static final int DEFAULT_BUFFER_SIZE
      See Also:

    • writer

      private final Writer writer

    • decoder

      private final CharsetDecoder decoder

    • writeImmediately

      private final boolean writeImmediately

    • decoderIn

      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.

    • decoderOut

      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.

  • Constructor Details

    • WriterOutputStream

      public WriterOutputStream(Writer writer, 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(Writer writer, 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(Writer writer, 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(Writer writer, 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(Writer writer, 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(Writer writer, 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

      public WriterOutputStream(Writer writer)
      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 Details

    • write

      public void write(byte[] b, int off, int len) throws IOException
      Write 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(byte[] b) throws IOException
      Write 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(int b) throws IOException
      Write 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

    • 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

    • 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 AutoCloseable
      Specified by:
      close in interface Closeable
      Overrides:
      close in class OutputStream
      Throws:
      IOException - if an I/O error occurs

    • processInput

      private void processInput(boolean endOfInput) throws IOException
      Decode the contents of the input ByteBuffer into a CharBuffer.
      Parameters:
      endOfInput - indicates end of input
      Throws:
      IOException - if an I/O error occurs

    • flushOutput

      private void flushOutput() throws IOException
      Flush the output.
      Throws:
      IOException - if an I/O error occurs