Package org.apache.commons.io.input

# Class ReaderInputStream

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

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class ReaderInputStream extends AbstractInputStream
`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):

To build an instance, use `ReaderInputStream.Builder`.

     InputStream inputStream = ...
     Charset cs = ...
     InputStreamReader reader = new InputStreamReader(inputStream, cs);
     ReaderInputStream in2 = ReaderInputStream.builder()
       .setReader(reader)
       .setCharset(cs)
       .get();

`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, 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.

The `available()` method of this class always returns 0. The methods `InputStream.mark(int)` and `InputStream.reset()` are not supported.

Instances of `ReaderInputStream` are not thread safe.

Since:
  2.0
See Also:
  - `ReaderInputStream.Builder`
  - `WriterOutputStream`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ReaderInputStream.Builder`
  Builds a new `ReaderInputStream`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ReaderInputStream(Reader reader)`
  Deprecated.
  Use `builder()` instead
  `ReaderInputStream(Reader reader, String charsetName)`
  Deprecated.
  Use `builder()` instead
  `ReaderInputStream(Reader reader, String charsetName, int bufferSize)`
  Deprecated.
  Use `builder()` instead
  `ReaderInputStream(Reader reader, Charset charset)`
  Deprecated.
  Use `builder()` instead, will be protected for subclasses.
  `ReaderInputStream(Reader reader, CharsetEncoder charsetEncoder)`
  Deprecated.
  Use `builder()` instead
  `ReaderInputStream(Reader reader, CharsetEncoder charsetEncoder, int bufferSize)`
  Deprecated.
  Use `builder()` instead
  `ReaderInputStream(Reader reader, Charset charset, int bufferSize)`
  Deprecated.
  Use `builder()` instead

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `available()`
  `static ReaderInputStream.Builder`
  `builder()`
  Constructs a new `ReaderInputStream.Builder`.
  `void`
  `close()`
  Closes the stream.
  `int`
  `read()`
  Reads a single byte.
  `int`
  `read(byte[] b)`
  Reads the specified number of bytes into an array.
  `int`
  `read(byte[] array, int off, int len)`
  Reads the specified number of bytes into an array.

  ### Methods inherited from class org.apache.commons.io.input.AbstractInputStream

  `isClosed, setClosed`

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

  `mark, markSupported, reset, skip`

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream` that uses the virtual machine's `default charset` with a default input buffer size of 8192 characters.
    Parameters:
      `reader` - the target `Reader`

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, Charset charset)
    Deprecated.
    Use `builder()` instead, will be protected for subclasses.
    Constructs a new `ReaderInputStream` with a default input buffer size of 8192 characters.

    The encoder created for the specified charset will use `CodingErrorAction.REPLACE` for malformed input and unmappable characters.

    Parameters:
      `reader` - the target `Reader`
      `charset` - the charset encoding

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, Charset charset, int bufferSize)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream`.

    The encoder created for the specified charset will use `CodingErrorAction.REPLACE` for malformed input and unmappable characters.

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

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, CharsetEncoder charsetEncoder)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream`.

    This constructor does not call `reset` on the provided encoder. The caller of this constructor should do this when providing an encoder which had already been in use.

    Parameters:
      `reader` - the target `Reader`
      `charsetEncoder` - the charset encoder
    Since:
      2.1

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, CharsetEncoder charsetEncoder, int bufferSize)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream`.

    This constructor does not call `reset` on the provided encoder. The caller of this constructor should do this when providing an encoder which had already been in use.

    Parameters:
      `reader` - the target `Reader`
      `charsetEncoder` - the charset encoder, null defaults to the default Charset encoder.
      `bufferSize` - the size of the input buffer in number of characters
    Since:
      2.1

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, String charsetName)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream` with a default input buffer size of 8192 characters.

    The encoder created for the specified charset will use `CodingErrorAction.REPLACE` for malformed input and unmappable characters.

    Parameters:
      `reader` - the target `Reader`
      `charsetName` - the name of the charset encoding

  - ### ReaderInputStream

    @Deprecated public ReaderInputStream(Reader reader, String charsetName, int bufferSize)
    Deprecated.
    Use `builder()` instead
    Constructs a new `ReaderInputStream`.

    The encoder created for the specified charset will use `CodingErrorAction.REPLACE` for malformed input and unmappable characters.

    Parameters:
      `reader` - the target `Reader`
      `charsetName` - the name of the charset encoding, null maps to the default Charset.
      `bufferSize` - the size of the input buffer in number of characters

- ## Method Details

  - ### builder

    public static ReaderInputStream.Builder builder()
    Constructs a new `ReaderInputStream.Builder`.
    Returns:
      a new `ReaderInputStream.Builder`.
    Since:
      2.12.0

  - ### available

    public int available() throws IOException
    Overrides:
      `available` in class `InputStream`
    Throws:
      `IOException`

  - ### close

    public void close() throws IOException
    Closes the stream. This method will cause the underlying `Reader` to be closed.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `AbstractInputStream`
    Throws:
      `IOException` - if an I/O error occurs.

  - ### read

    public int read() throws IOException
    Reads a single byte.
    Specified by:
      `read` in class `InputStream`
    Returns:
      either the byte read or `-1` if the end of the stream has been reached
    Throws:
      `IOException` - if an I/O error occurs.

  - ### read

    public int read(byte[] b) throws IOException
    Reads the specified number of bytes into an array.
    Overrides:
      `read` in class `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:
      `IOException` - if an I/O error occurs.

  - ### read

    public int read(byte[] array, int off, int len) throws IOException
    Reads the specified number of bytes into an array.
    Overrides:
      `read` in class `InputStream`
    Parameters:
      `array` - 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:
      `IOException` - if an I/O error occurs.