org.apache.commons.io.input
Class ReaderInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by org.apache.commons.io.input.ReaderInputStream
All Implemented Interfaces:
Closeable

public class ReaderInputStream
extends 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 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

Constructor Summary
ReaderInputStream(Reader reader)
          Construct a new ReaderInputStream that uses the default character encoding with a default input buffer size of 1024 characters.
ReaderInputStream(Reader reader, Charset charset)
          Construct a new ReaderInputStream with a default input buffer size of 1024 characters.
ReaderInputStream(Reader reader, CharsetEncoder encoder)
          Construct a new ReaderInputStream.
ReaderInputStream(Reader reader, CharsetEncoder encoder, int bufferSize)
          Construct a new ReaderInputStream.
ReaderInputStream(Reader reader, Charset charset, int bufferSize)
          Construct a new ReaderInputStream.
ReaderInputStream(Reader reader, String charsetName)
          Construct a new ReaderInputStream with a default input buffer size of 1024 characters.
ReaderInputStream(Reader reader, String charsetName, int bufferSize)
          Construct a new ReaderInputStream.
 
Method Summary
 void close()
          Close the stream.
 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
 

Constructor Detail

ReaderInputStream

public ReaderInputStream(Reader reader,
                         CharsetEncoder encoder)
Construct a new ReaderInputStream.

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

ReaderInputStream

public ReaderInputStream(Reader reader,
                         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(Reader reader,
                         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(Reader reader,
                         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(Reader reader,
                         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(Reader reader,
                         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

public ReaderInputStream(Reader reader)
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

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException
Read the specified number of bytes into an array.

Overrides:
read in class 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:
IOException - if an I/O error occurs

read

public int read(byte[] b)
         throws IOException
Read 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()
         throws IOException
Read 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

close

public void close()
           throws IOException
Close the stream. This method will cause the underlying Reader to be closed.

Specified by:
close in interface Closeable
Overrides:
close in class InputStream
Throws:
IOException - if an I/O error occurs


Copyright © 2002-2012 The Apache Software Foundation. All Rights Reserved.