Java Character Streams: Reader and Writer

A file menu.txt is saved in UTF-8 and contains one word: «café». A Java 17 program running on Windows with a US or Western European locale reads it with new FileReader("menu.txt") and prints café. The code has no bug: FileReader without an explicit charset used the system default, windows-1252. How to avoid this, and which character stream class to use for what, is covered below.

Character streams in Java are classes of the java.io package that read and write text as char values (16-bit UTF-16 units) rather than as raw bytes. Every character input stream extends the abstract class Reader, and every character output stream extends Writer. A file or a network connection always holds bytes, so a character stream attached to a file converts bytes to characters and back using a charset (Charset). The general split into byte and character streams is explained in the lesson Java I/O Streams.

1. The Reader class

Reader is the abstract class that every character input stream in Java extends. Its read() methods return the next character as an int from 0 to 65535, or -1 when the stream is over. On an I/O error the methods of the class throw IOException.

Reader methods

Since Java 11 there is a factory method Reader.nullReader(): an empty reader that returns -1 right away. It is a handy stub in tests.

2. The Writer class

Writer is the abstract class that every character output stream extends. It defines write() and append() for writing characters, arrays and strings, flush() for pushing buffered data out, and close() for closing the destination. On an I/O error the methods throw IOException.

Writer methods

Like Reader, Java 11 added Writer.nullWriter(): a writer that silently discards everything written to it.

3. FileReader and FileWriter

FileReader reads characters from a text file, and FileWriter writes characters to a file. Their constructors take a path as a string or a File object (see the lesson Java File Class). Under the hood they are subclasses of InputStreamReader and OutputStreamWriter: they open a file byte stream and convert bytes to characters using a charset.

FileReader and FileWriter constructors

Before Java 11, FileReader and FileWriter had no Charset parameter, so to read or write text in a specific encoding you had to build a chain with InputStreamReader/OutputStreamWriter (see the next section).

Example 1. Writing and reading a file with FileWriter and FileReader

The streams are closed automatically by try-with-resources. Writing and reading happen in two separate blocks: by the time we read, the FileWriter is already closed and every character is guaranteed to be in the file.

import java.io.File;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class FileWriterReaderExample {
    public static void main(String[] args) {
        File file = new File("fileWrite.txt");

        try (FileWriter writer = new FileWriter(file, StandardCharsets.UTF_8)) {
            writer.write("Learn\nJava!\n");
        } catch (IOException e) {
            System.out.println("Write error: " + e.getMessage());
        }

        try (FileReader reader = new FileReader(file, StandardCharsets.UTF_8)) {
            char[] buffer = new char[50];
            int total = 0;
            int count;
            while ((count = reader.read(buffer)) != -1) { // read until the end of the file
                System.out.print(new String(buffer, 0, count));
                total += count;
            }
            System.out.println("Characters read: " + total);
        } catch (IOException e) {
            System.out.println("Read error: " + e.getMessage());
        }
    }
}
// Output:
// Learn
// Java!
// Characters read: 12

Why 12: five characters in Learn, five in Java! and two line feeds \n. If you run only the second half without the file, the FileReader constructor throws FileNotFoundException, and the program prints Read error: fileWrite.txt (No such file or directory) on Linux/macOS (on Windows the reason reads The system cannot find the file specified).

4. InputStreamReader and OutputStreamWriter

InputStreamReader and OutputStreamWriter are the bridge between byte and character streams. InputStreamReader wraps any InputStream and decodes bytes into characters; OutputStreamWriter wraps an OutputStream and encodes characters into bytes. The charset is the second constructor argument — usually StandardCharsets.UTF_8.

new InputStreamReader(InputStream in)                      // default charset
new InputStreamReader(InputStream in, Charset cs)          // explicit charset
new InputStreamReader(InputStream in, String charsetName)  // UnsupportedEncodingException for an unknown name

new OutputStreamWriter(OutputStream out)
new OutputStreamWriter(OutputStream out, Charset cs)
new OutputStreamWriter(OutputStream out, String charsetName)

The getEncoding() method returns the historical name of the charset the stream uses, for example UTF8 or Cp1252. You need these classes wherever a source gives you bytes but you want to work with text: a file (FileInputStream), a network connection, or the console System.in:

BufferedReader console = new BufferedReader(new InputStreamReader(System.in));
String name = console.readLine(); // the line typed on the keyboard

How to build a full chain "file → charset → buffer → formatting" from these classes, and why the default charset depended on the OS before Java 18, is shown in the section A chain of wrappers of the I/O streams lesson.

What does this code print?

The program writes the word «café» in UTF-8 and then reads it twice: as windows-1252 and as UTF-8.

import java.io.*;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;

public class EncodingDemo {
    public static void main(String[] args) throws IOException {
        try (Writer out = new OutputStreamWriter(
                new FileOutputStream("menu.txt"), StandardCharsets.UTF_8)) {
            out.write("café");
        }

        try (BufferedReader in = new BufferedReader(new InputStreamReader(
                new FileInputStream("menu.txt"), Charset.forName("windows-1252")))) {
            String line = in.readLine();
            System.out.println(line + " (" + line.length() + " characters)");
        }

        try (BufferedReader in = new BufferedReader(new InputStreamReader(
                new FileInputStream("menu.txt"), StandardCharsets.UTF_8))) {
            String line = in.readLine();
            System.out.println(line + " (" + line.length() + " characters)");
        }
    }
}
// Output:
// café (5 characters)
// café (4 characters)

In UTF-8, é takes two bytes, C3 A9, so the file holds 5 bytes for 4 letters. windows-1252 is a single-byte charset: it turns every byte into a separate character, so C3 becomes Ã and A9 becomes ©. There is no error and no exception — that is exactly why the charset must be given explicitly on both sides, when writing and when reading.

5. BufferedReader and BufferedWriter

BufferedReader and BufferedWriter are wrappers around another character stream with an internal buffer of 8192 characters. BufferedReader fills the buffer in large blocks and adds readLine() for reading text line by line; BufferedWriter collects characters in the buffer, writes them to the inner stream in blocks and adds newLine().

BufferedReader(Reader in)
BufferedReader(Reader in, int size)   // size - buffer size in characters
BufferedWriter(Writer out)
BufferedWriter(Writer out, int size)

The first argument is the stream to read from or write to (most often FileReader/FileWriter or InputStreamReader/OutputStreamWriter), the second is the buffer size. The buffer cuts the number of file accesses: instead of a system call per character, the stream goes to the disk once per block.

• String readLine() returns the next line without the line terminator (\n, \r or \r\n), and null when the file is over. An empty line in the file comes back as "", not null.
• void newLine() writes the line separator of the current OS: \r\n on Windows, \n on Linux and macOS.
• Stream<String> lines() (Java 8) returns the lines of the file as a Stream API stream: long n = reader.lines().count();

Example 2. Writing with BufferedWriter and reading with BufferedReader

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class BufferedExample {
    public static void main(String[] args) {
        try (BufferedWriter writer = new BufferedWriter(
                new FileWriter("buffered.txt", StandardCharsets.UTF_8))) {
            writer.write("Hello, world!");
            writer.newLine();
            writer.newLine();          // an empty line
            writer.write("The end");   // last line without a line separator
        } catch (IOException e) {
            System.out.println("Write error: " + e.getMessage());
        }

        try (BufferedReader reader = new BufferedReader(
                new FileReader("buffered.txt", StandardCharsets.UTF_8))) {
            String line;
            while ((line = reader.readLine()) != null) { // null - end of file
                System.out.println("[" + line + "] length " + line.length());
            }
        } catch (IOException e) {
            System.out.println("Read error: " + e.getMessage());
        }
    }
}
// Output:
// [Hello, world!] length 13
// [] length 0
// [The end] length 7

The square brackets show that readLine() dropped the line terminators, the empty line came back as "", and the last line was read even without a trailing separator. It is enough to close the outer wrapper: BufferedWriter.close() flushes the buffer and closes the nested FileWriter. Why you should never close the inner stream first is explained in Which stream to close.

6. PrintWriter

PrintWriter is a character output stream with convenient print(), println(), printf() and format() methods that turn values of any type into text. It extends Writer and, unlike other streams, does not throw IOException from its writing methods: errors are reported through checkError().

PrintWriter constructors

The file-name constructors cannot append to an existing file — for that, wrap a FileWriter in append mode: new PrintWriter(new FileWriter("log.txt", true)).

PrintWriter methods

• print(x) — writes a value of any type as text, without a line separator.
• println(x) — the same, followed by the OS line separator.
• printf(format, args...) and format(format, args...) — identical methods for formatted output with a pattern (%d, %s, %.2f, %n).
• write(...) — methods inherited from Writer that write characters and strings as is.
• boolean checkError() — flushes the stream and returns true if any write has failed.

Example 3. Writing to a file with PrintWriter

import java.io.IOException;
import java.io.PrintWriter;
import java.nio.charset.StandardCharsets;

public class PrintWriterExample {
    public static void main(String[] args) {
        String s1 = "Welcome to the café!";
        String s2 = "Hello World!";
        try (PrintWriter printWriter = new PrintWriter("notes.txt", StandardCharsets.UTF_8)) {
            printWriter.println(s1);
            int i = 2;
            printWriter.printf("The square of %d is %d%n", i, i * i);
            printWriter.write(s2);
            printWriter.print("The end");
        } catch (IOException e) {
            System.out.println("Cannot open the file: " + e.getMessage());
            return;
        }
        System.out.println("The file has been written");
    }
}
// Console output:
// The file has been written

The message is printed after the try block, when the PrintWriter is already closed and the data is flushed to the file. Contents of notes.txt:

Welcome to the café!
The square of 2 is 4
Hello World!The end

The last line got glued together: neither write() nor print() adds a line separator — only println() and %n in a printf() pattern do. The catch block here catches only a constructor failure: the println()/printf() calls themselves never throw.

7. Character stream gotchas

Most bugs with character streams come from the default charset, overwriting a file instead of appending, buffering, and the fact that PrintWriter stays silent on failure. All of them compile without warnings and show up only on specific data or a specific OS.

What does this code print?

PrintWriter pw = new PrintWriter(new StringWriter());
pw.close();
pw.println("after close");
System.out.println(pw.checkError());

Answer: the program does not crash and prints true. Writing to a closed PrintWriter internally raises IOException: Stream closed, but println() catches it and only sets an error flag. The same call on a closed BufferedWriter (bw.write("after close")) throws IOException immediately. So PrintWriter is convenient for reports and console-style output, but wherever losing data is unacceptable, check for errors explicitly.

8. Table of character stream classes

The java.io package has about twenty character streams. Almost every one has a byte counterpart (FileReader — FileInputStream, BufferedWriter — BufferedOutputStream), and the classes fall into sources and destinations of data (a file, a string, an array, a pipe) and wrappers that add features to another stream.

Byte streams and their classes are covered in the lesson Java Byte Streams. Character streams are not suitable for binary data (images, archives): decoding it with a charset corrupts the file.