WriterOutputStream (Commons IO 2.5)
Date: 2016-12-01

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 and Description
    --- | ---
    `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 static int` | `DEFAULT_BUFFER_SIZE`
    `private boolean` | `writeImmediately`
    `private java.io.Writer` | `writer`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WriterOutputStream(java.io.Writer writer)` Deprecated. 2.5 use `WriterOutputStream(Writer, Charset)` instead
    `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`.
    `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`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static void` | `checkIbmJdkWithBrokenUTF16(java.nio.charset.Charset 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.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_BUFFER_SIZE

          private static final int DEFAULT_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.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      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)

Copyright (c) 2002-2016 Apache Software Foundation