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

org.apache.commons.io.input

## Class ReaderInputStream

- java.lang.Object
- - java.io.InputStream
  - - org.apache.commons.io.input.ReaderInputStream

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class ReaderInputStream
      extends java.io.InputStream

  `InputStream` implementation that reads a character stream from a `Reader` and transforms it to a byte stream using a specified charset encoding. The stream is transformed using a `CharsetEncoder` object, guaranteeing that all charset encodings supported by the JRE are handled correctly. In particular for charsets such as UTF-16, the implementation ensures that one and only one byte order marker is produced.

  Since in general it is not possible to predict the number of characters to be read from the `Reader` to satisfy a read request on the `ReaderInputStream`, all reads from the `Reader` are buffered. There is therefore no well defined correlation between the current position of the `Reader` and that of the `ReaderInputStream`. This also implies that in general there is no need to wrap the underlying `Reader` in a `BufferedReader`.

  `ReaderInputStream` implements the inverse transformation of `InputStreamReader`; in the following example, reading from `in2` would return the same byte sequence as reading from `in` (provided that the initial byte sequence is legal with respect to the charset encoding):

       InputStream in = ...
       Charset cs = ...
       InputStreamReader reader = new InputStreamReader(in, cs);
       ReaderInputStream in2 = new ReaderInputStream(reader, cs);

  `ReaderInputStream` implements the same transformation as `OutputStreamWriter`, except that the control flow is reversed: both classes transform a character stream into a byte stream, but `OutputStreamWriter` pushes data to the underlying stream, while `ReaderInputStream` pulls it from 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 `InputStream`, but where the most natural way to produce the data is as a character stream, i.e. by providing a `Reader` instance. An example of a situation where this problem may appear is when implementing the `javax.activation.DataSource` interface from the Java Activation Framework.

  Given the fact that the `Reader` class doesn't provide any way to predict whether the next read operation will block or not, it is not possible to provide a meaningful implementation of the `InputStream.available()` method. A call to this method will always return 0. Also, this class doesn't support `InputStream.mark(int)`.

  Instances of `ReaderInputStream` are not thread safe.

  Since:
    2.0
  See Also:
    `WriterOutputStream`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static int` | `DEFAULT_BUFFER_SIZE`
    `private java.nio.charset.CharsetEncoder` | `encoder`
    `private java.nio.CharBuffer` | `encoderIn` CharBuffer used as input for the decoder.
    `private java.nio.ByteBuffer` | `encoderOut` ByteBuffer used as output for the decoder.
    `private boolean` | `endOfInput`
    `private java.nio.charset.CoderResult` | `lastCoderResult`
    `private java.io.Reader` | `reader`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReaderInputStream(java.io.Reader reader)` Deprecated. 2.5 use `ReaderInputStream(Reader, Charset)` instead
    `ReaderInputStream(java.io.Reader reader, java.nio.charset.Charset charset)` Construct a new `ReaderInputStream` with a default input buffer size of 1024 characters.
    `ReaderInputStream(java.io.Reader reader, java.nio.charset.CharsetEncoder encoder)` Construct a new `ReaderInputStream`.
    `ReaderInputStream(java.io.Reader reader, java.nio.charset.CharsetEncoder encoder, int bufferSize)` Construct a new `ReaderInputStream`.
    `ReaderInputStream(java.io.Reader reader, java.nio.charset.Charset charset, int bufferSize)` Construct a new `ReaderInputStream`.
    `ReaderInputStream(java.io.Reader reader, java.lang.String charsetName)` Construct a new `ReaderInputStream` with a default input buffer size of 1024 characters.
    `ReaderInputStream(java.io.Reader reader, java.lang.String charsetName, int bufferSize)` Construct a new `ReaderInputStream`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the stream.
    `private void` | `fillBuffer()` Fills the internal char buffer from the reader.
    `int` | `read()` Read a single byte.
    `int` | `read(byte[] b)` Read the specified number of bytes into an array.
    `int` | `read(byte[] b, int off, int len)` Read the specified number of bytes into an array.

    - ### Methods inherited from class java.io.InputStream

      `available, mark, markSupported, reset, skip`

    - ### 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

    - #### reader

          private final java.io.Reader reader

    - #### encoder

          private final java.nio.charset.CharsetEncoder encoder

    - #### encoderIn

          private final java.nio.CharBuffer encoderIn

      CharBuffer used as input for the decoder. It should be reasonably large as we read data from the underlying Reader into this buffer.

    - #### encoderOut

          private final java.nio.ByteBuffer encoderOut

      ByteBuffer used as output for the decoder. This buffer can be small as it is only used to transfer data from the decoder to the buffer provided by the caller.

    - #### lastCoderResult

          private java.nio.charset.CoderResult lastCoderResult

    - #### endOfInput

          private boolean endOfInput

  - ### Constructor Detail

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.nio.charset.CharsetEncoder encoder)

      Construct a new `ReaderInputStream`.
      Parameters:
        `reader` - the target `Reader`
        `encoder` - the charset encoder
      Since:
        2.1

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.nio.charset.CharsetEncoder encoder,
                           int bufferSize)

      Construct a new `ReaderInputStream`.
      Parameters:
        `reader` - the target `Reader`
        `encoder` - the charset encoder
        `bufferSize` - the size of the input buffer in number of characters
      Since:
        2.1

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.nio.charset.Charset charset,
                           int bufferSize)

      Construct a new `ReaderInputStream`.
      Parameters:
        `reader` - the target `Reader`
        `charset` - the charset encoding
        `bufferSize` - the size of the input buffer in number of characters

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.nio.charset.Charset charset)

      Construct a new `ReaderInputStream` with a default input buffer size of 1024 characters.
      Parameters:
        `reader` - the target `Reader`
        `charset` - the charset encoding

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.lang.String charsetName,
                           int bufferSize)

      Construct a new `ReaderInputStream`.
      Parameters:
        `reader` - the target `Reader`
        `charsetName` - the name of the charset encoding
        `bufferSize` - the size of the input buffer in number of characters

    - #### ReaderInputStream

          public ReaderInputStream(java.io.Reader reader,
                           java.lang.String charsetName)

      Construct a new `ReaderInputStream` with a default input buffer size of 1024 characters.
      Parameters:
        `reader` - the target `Reader`
        `charsetName` - the name of the charset encoding

    - #### ReaderInputStream

          @Deprecated
          public ReaderInputStream(java.io.Reader reader)

      Deprecated. 2.5 use `ReaderInputStream(Reader, Charset)` instead
      Construct a new `ReaderInputStream` that uses the default character encoding with a default input buffer size of 1024 characters.
      Parameters:
        `reader` - the target `Reader`

  - ### Method Detail

    - #### fillBuffer

          private void fillBuffer()
                           throws java.io.IOException

      Fills the internal char buffer from the reader.
      Throws:
        `java.io.IOException` - If an I/O error occurs

    - #### read

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

      Read the specified number of bytes into an array.
      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `b` - the byte array to read into
        `off` - the offset to start reading bytes into
        `len` - the number of bytes to read
      Returns:
        the number of bytes read or `-1` if the end of the stream has been reached
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          public int read(byte[] b)
                   throws java.io.IOException

      Read the specified number of bytes into an array.
      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `b` - the byte array to read into
      Returns:
        the number of bytes read or `-1` if the end of the stream has been reached
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### read

          public int read()
                   throws java.io.IOException

      Read a single byte.
      Specified by:
        `read` in class `java.io.InputStream`
      Returns:
        either the byte read or `-1` if the end of the stream has been reached
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### close

          public void close()
                     throws java.io.IOException

      Close the stream. This method will cause the underlying `Reader` to be closed.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.InputStream`
      Throws:
        `java.io.IOException` - if an I/O error occurs

Copyright (c) 2002-2016 Apache Software Foundation