Tech and Media Labs
This site uses cookies to improve the user experience.


Java IO: InputStreamReader

Jakob Jenkov
Last update: 2018-09-12

The Java InputStreamReader class (java.io.InputStreamReader) is intended to wrap an InputStream, thereby turning the byte based input stream into a character based Reader. In other words, the Java InputStreamReader interprets the bytes of a Java InputStream as text instead of numerical data.

The Java InputStreamReader is often used to read characters from files (or network connections) where the bytes represents text. For instance, a text file where the characters are encoded as UTF-8. You could use an InputStreamReader to wrap a FileInputStream in order to read such a file.

InputStreamReader Example

Here is a Java InputStreamReader example:

InputStream inputStream       = new FileInputStream("c:\\data\\input.txt");
Reader      inputStreamReader = new InputStreamReader(inputStream);

int data = inputStreamReader.read();
while(data != -1){
    char theChar = (char) data;
    data = inputStreamReader.read();
}

inputStreamReader.close();

This example first creates a FileInputStream and then wraps it in an InputStreamReader. Second, the example reads all characters from the file via the InputStreamReader

Note: The proper exception handling has been skipped here for the sake of clarity. To learn more about correct exception handling, go to Java IO Exception Handling.

Creating an InputStreamReader

To create a Java InputStreamReader you simply instantiate it like any other object, passing an InputStream to its constructor. Here is an example:

InputStream inputStream       = new FileInputStream("c:\\data\\input.txt");
Reader      inputStreamReader = new InputStreamReader(inputStream);

This is all it takes to create an InputStreamReader .

Specifying the Character Set

The characters in underlying InputStream will be encoded using some character encoding. This character encoding is referred to as a character set, or Charset in Java. Two of the commonly used character sets are ASCII (or ISO-Latin1) and UTF8 (or UTF-16 in some cases).

You need to tell the InputStreamReader instance what character sets the characters in the InputStream are encoded with. You do so in the InputStreamReader constructor. Here is an example of setting the character set to be used by a Java InputStreamReader:

InputStream inputStream = new FileInputStream("data.txt");

InputStreamReader inputStreamReader =
    new InputStreamReader(inputStream, Charset.forName("UTF-8"));

As you can see, the character set is passed as the second parameter to the InputStreamReader constructor. In the example above, the character used is UTF-8.

read()

The read() method of an InputStreamReader returns an int which contains the char value of the char read. Here is a Java InputStreamReader read() example:

int data = inputStreamReader.read();

You can cast the returned int to a char like this:

char aChar = (char) data;

End of Stream

If the read() method returns -1, the end of stream has been reached, meaning there is no more data to read in the InputStreamReader. That is, -1 as int value, not -1 as byte or short value. There is a difference here!

When the end of stream has been reached, you can close the InputStreamReader.

You typically read from a Java InputStreamReader inside a while loop, like this:

int data = inputStreamReader.read();
while(data != -1) {
    char theChar = (char) data;
    data = inputStreamReader.read();
}

inputStreamReader.close();

As you can see, the while loop keeps running until a -1 is read from the InputStreamReader read() method. After that, the InputStreamReader is closed. See the next section for more information about how to close an InputStreamReader correctly.

Closing an InputStreamReader

When you are finished reading characters from the InputStreamReader you should remember to close it. Closing an InputStreamReader will also close the InputStream instance from which the InputStreamReader is reading.

Closing an InputStreamReader is done by calling its close() method. Here is how closing an InputStreamReader looks:

inputStreamReader.close();

You can also use the Java try with resources construct introduced in Java 7. Here is how to use and close a InputStreamReader looks with the try-with-resources construct:

InputStream input = new FileInputStream("data/text.txt");

try(InputStreamReader inputStreamReader =
    new InputStreamReader(input)){

    int data = inputStreamReader.read();
    while(data != -) {
        System.out.print((char) data));
        data = inputStreamReader.read();
    }
    
}

Notice how there is no longer any explicit close() method call. The try-with-resources construct takes care of that.

Notice also that the first FileInputStream instance is not created inside the try-with-resources block. That means that the try-with-resources block will not automatically close this FileInputStream instance. However, when the InputStreamReader is closed it will also close the InputStream instance it reads from, so the FileInputStream instance will get closed when the InputStreamReader is closed.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC