{@link InputStream} implementation that reads a character stream from a {@link Reader}and transforms it to a byte stream using a specified charset encoding. The stream is transformed using a {@link CharsetEncoder} object, guaranteeing that all charsetencodings 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 {@link Reader} to satisfy a read request on the {@link ReaderInputStream}, all reads from the {@link Reader} are buffered. There is therefore no well defined correlationbetween the current position of the {@link Reader} and that of the {@link ReaderInputStream}. This also implies that in general there is no need to wrap the underlying {@link Reader}in a {@link java.io.BufferedReader}.
{@link ReaderInputStream} implements the inverse transformation of {@link java.io.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);
{@link ReaderInputStream} implements the same transformation as {@link java.io.OutputStreamWriter}, except that the control flow is reversed: both classes transform a character stream into a byte stream, but {@link java.io.OutputStreamWriter} pushes data to the underlying stream,while {@link 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 {@link InputStream}, but where the most natural way to produce the data is as a character stream, i.e. by providing a {@link Reader} instance. An example of a situationwhere this problem may appear is when implementing the {@link javax.activation.DataSource}interface from the Java Activation Framework.
Given the fact that the {@link Reader} class doesn't provide any way to predict whether the nextread operation will block or not, it is not possible to provide a meaningful implementation of the {@link InputStream#available()} method. A call to this methodwill always return 0. Also, this class doesn't support {@link InputStream#mark(int)}.
Instances of {@link ReaderInputStream} are not thread safe.
@see org.apache.commons.io.output.WriterOutputStream
@author Andreas Veithen
@since Commons IO 2.0