Skip to content
Tutorials Center
My learning

Topics

Lesson 114 of 201 ยท Input and Output

Byte and Character Streams

Understand Java I/O streams - InputStream and OutputStream for bytes, Reader and Writer for text, buffering, PrintWriter, InputStreamReader and closing with try-with-resources.

The one-line Files methods from Reading and Writing Files are perfect when a whole file fits in memory. But data doesn't always come from a file, and it isn't always small. It arrives from the keyboard, a network socket, a compressed archive, an HTTP response or another program, often as a continuous flow of unknown length. Java handles all of these with one idea: the stream, a sequence of data that you read or write piece by piece, in order.

(These I/O streams have nothing to do with the java.util.stream API from Streams; the name is an unlucky coincidence from Java 1.0 vs Java 8.)

This lesson explains the two families of streams, bytes and characters, and how to combine them like building blocks: a buffer here, a charset converter there. Once you understand the pattern, you can read and write any kind of data source with the same handful of classes, and you'll recognize what Files.newBufferedReader or System.out really are.

Two families: bytes and characters

Every I/O class in java.io belongs to one of four abstract base types:

Reading Writing Unit
Byte streams InputStream OutputStream byte (8 bits): images, ZIP files, any binary data
Character streams Reader Writer char (16 bits): text

Byte streams move raw bytes and know nothing about text. Character streams move characters, and somewhere underneath they convert characters to and from bytes using a charset such as UTF-8. Use byte streams for binary data and character streams for text, and you'll avoid a whole category of bugs.

Each base type has implementations for different sources and destinations:

  • Files: FileInputStream, FileOutputStream, FileReader, FileWriter
  • Memory: ByteArrayInputStream, ByteArrayOutputStream, StringReader, StringWriter
  • Other programs and the console: System.in (an InputStream), System.out and System.err (PrintStreams)
  • Networks: socket.getInputStream(), socket.getOutputStream() (TCP Sockets)

Other classes wrap an existing stream to add a feature: buffering, character conversion, formatting, compression. You'll see this wrapping pattern (the decorator design pattern) throughout the lesson.

Reading bytes with InputStream

The core method of InputStream is read(), which returns the next byte as an int from 0 to 255, or -1 at the end of the stream. In-memory streams make it easy to see how this works:

Java Reading bytes one at a time and in chunks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Three details trip up beginners:

  • read() returns an int, not a byte, so that -1 can mean "end" while all 256 byte values remain valid data. The byte -1 in the array comes back as 255; cast to byte if you need the signed value.
  • read(buffer) may fill fewer bytes than the buffer holds, even before the end, especially with network streams. Always use the returned count, as new String(buffer, 0, count) does. Using the whole buffer would repeat stale bytes from the previous chunk.
  • readAllBytes() (Java 9) and readNBytes(n) (Java 11) do the looping for you. readAllBytes loads everything into memory, so use it only when the data is small.

Writing bytes and copying streams

OutputStream.write sends bytes on their way. A classic job is copying one stream to another, and since Java 9 transferTo does it in one call:

Java Writing to files and copying with transferTo

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

ByteArrayOutputStream is a handy "sink" that collects bytes in memory and grows as needed; call toByteArray() or toString(charset) at the end. It's often used in tests and to build data before sending it somewhere. new FileOutputStream(name) replaces the file; new FileOutputStream(name, true) appends. In new code, Files.newOutputStream(path, options...) and Files.newInputStream(path) give you the same streams with the clearer Path API and the open options from the previous lesson.

Closing streams with try-with-resources

Every stream connected to a file, socket or process holds an operating-system resource that must be released with close(). Forgetting it leaks file handles, and for output streams it can lose data that was still waiting in a buffer. The reliable way to close is try-with-resources, which closes everything in reverse order of opening, even when an exception is thrown:

Java
try (InputStream in = Files.newInputStream(source);
     OutputStream out = Files.newOutputStream(target)) {
    in.transferTo(out);
}   // out is closed first, then in

Closing a wrapper closes the stream inside it, so when you wrap streams you only need to declare the outermost one (declaring each in the try also works and is safe). The details, including suppressed exceptions, are in try-with-resources.

Buffering: fewer, bigger operations

Every read() or write() on a FileInputStream or FileOutputStream is a call into the operating system, which is slow compared to working in memory. Reading a 1 MB file one byte at a time means a million system calls. A buffered stream wraps another stream and moves data in large blocks (8 KB by default), serving your small reads from memory. This demo counts how often the underlying stream is actually asked for data:

Java Counting the calls that buffering saves

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

With a buffer, the same 100,000 single-byte reads reach the source only 14 times instead of 100,001. When the source is a disk file or a network connection, that difference is enormous. The rules of thumb:

  • Wrap file and socket streams in BufferedInputStream/BufferedOutputStream, or BufferedReader/BufferedWriter for text, unless you already read and write in large chunks yourself (as transferTo and readAllBytes do).
  • Buffered output must be flushed. Data sits in the buffer until it fills up, you call flush(), or you close() the stream. If a program exits without closing, the last part of the output is lost.
  • Files.newBufferedReader and Files.newBufferedWriter return already-buffered text streams, which is why they're the usual choice for files.

Character streams: Reader and Writer

Text needs characters, not bytes. Reader and Writer mirror the byte classes but work with char. The most useful character classes are:

  • BufferedReader: buffering plus readLine(), which returns one line without its line separator, or null at the end; and lines(), a Stream<String>.
  • BufferedWriter: buffering plus newLine().
  • StringReader / StringWriter: read from or write into a String in memory.
  • PrintWriter: print, println, printf and format on top of any Writer or OutputStream.
Java BufferedReader, PrintWriter and StringWriter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The while ((line = reader.readLine()) != null) loop is one of the most common idioms in Java; it reads any text source line by line with constant memory use. Note that printf here uses the default locale for the decimal separator; pass Locale.ROOT as the first argument for machine-readable output (Locales and Internationalization).

PrintWriter and PrintStream swallow exceptions. Their print methods never throw IOException. If the disk fills up, writes fail silently, and you only find out by calling checkError(), which returns true after any failure. For files that must be written correctly, use BufferedWriter (which does throw) or check checkError() before you report success.

Bridging bytes and characters

Some sources only give you bytes, but you need text: System.in, a socket, an HTTP body, a file inside a ZIP. InputStreamReader turns an InputStream into a Reader by decoding bytes with a charset, and OutputStreamWriter does the opposite. This is the bridge between the two families:

Java Wrapping byte streams in readers and writers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The Input box feeds System.in, and readLine() returns null when the input ends, just as it would at the end of a file. (We don't close console here, because closing it would close System.in too.) The second half shows why the charset matters: รผ, รŸ and โ‚ฌ need more than one byte each in UTF-8. Always pass the charset explicitly to InputStreamReader and OutputStreamWriter; the full story is in Character Sets and Encoding.

FileReader and FileWriter are shortcuts for "file stream + bridge". Before Java 11 they couldn't take a charset and always used the platform default, which caused countless bugs on Windows. Today you can write new FileReader(file, StandardCharsets.UTF_8), but Files.newBufferedReader(path) is shorter and defaults to UTF-8.

Binary data with DataOutputStream

When you need to write numbers, not text, DataOutputStream and DataInputStream write Java primitives in a fixed binary format (big-endian, the same on every platform). They're the building blocks of many file formats and network protocols:

Java
try (var out = new DataOutputStream(new BufferedOutputStream(Files.newOutputStream(path)))) {
    out.writeInt(3);              // 4 bytes
    out.writeDouble(19.99);       // 8 bytes
    out.writeUTF("Notebook");     // 2-byte length + modified UTF-8
}
try (var in = new DataInputStream(new BufferedInputStream(Files.newInputStream(path)))) {
    int count = in.readInt();     // must read in exactly the same order
    double price = in.readDouble();
    String name = in.readUTF();
}

Reading must follow the writing order exactly; there are no field names or markers in the data. For whole objects, see Serialization; for data exchanged with other systems, text formats like JSON are usually a better choice.

RandomAccessFile: jumping around in a file

Streams are sequential: you read from the start and move forward. RandomAccessFile is the exception. It keeps a file pointer that you can move with seek(position), and every read or write happens at the pointer, which then advances. That makes it the right tool for files of fixed-size records, where record i lives at byte i ร— recordSize, and for patching a few bytes in the middle of a large file without rewriting it.

It opens in mode "r" (read only) or "rw" (read and write, creating the file if needed), and it has the same readInt/writeDouble/readUTF methods as the data streams. length() gives the size, getFilePointer() the current position, and setLength truncates or extends the file.

Java Fixed-size records with RandomAccessFile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Each record is 12 bytes (a double plus an int), so record 3 starts at byte 36. Notice that overwriting a record in place leaves the length unchanged, and appending means seeking to length() first. For new code that needs the same power with buffers and channels, see FileChannel in NIO and the Files API.

Mark, reset and skip; chaining and descriptors

Some streams and readers can remember a position. mark(readLimit) notes the current spot and reset() goes back to it, as long as you haven't read more than readLimit characters in between. Always ask markSupported() first: BufferedReader, BufferedInputStream and the in-memory classes support it, while FileInputStream and most network streams do not. skip(n) discards up to n items and returns how many it really skipped, so check the result (or use skipNBytes, which throws if the stream ends early).

Wrapping streams is how you combine behaviors: FileOutputStream writes to the disk, BufferedOutputStream adds a buffer, and DataOutputStream adds typed methods. flush() moves data down one level; to push it all the way to the physical disk you need getFD().sync() on the underlying FileOutputStream. A FileDescriptor is the small handle that represents the open file for the operating system; valid() tells you whether it is still open.

Java mark/reset, buffer chain, FileDescriptor, append

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

A few remarks:

  • Closing the outermost stream closes everything inside it, so a try-with-resources over the wrapper is enough. We kept a reference to the inner FileOutputStream here only to reach its descriptor.
  • FileWriter(file, charset, true) appends instead of replacing. The true flag is the same convention as new FileOutputStream(name, true).
  • Temporary files for experiments come from Files.createTempFile (see Files and Paths); they are deleted with Files.delete once you are done.
  • Java also has java.io.FilePermission, which names a file and an action (read, write, delete, execute). It only matters under the old Security Manager policy files. Because the Security Manager is permanently disabled in current Java, you will meet this class mostly in old code; use the operating system's file permissions (Files.setPosixFilePermissions) for real access control.

Choosing the right class

Task Use
Read or write a small file at once Files.readString, Files.writeString, Files.readAllBytes
Read a text file line by line Files.newBufferedReader(path) + readLine(), or Files.lines(path)
Write a lot of text Files.newBufferedWriter(path), wrapped in PrintWriter for formatting
Copy any stream to another in.transferTo(out)
Text from a byte source (System.in, a socket) new BufferedReader(new InputStreamReader(in, UTF_8))
Build bytes or text in memory ByteArrayOutputStream, StringWriter
Test code that reads streams ByteArrayInputStream, StringReader
Throw away output OutputStream.nullOutputStream(), Writer.nullWriter() (Java 11)

Writing your methods against the abstract types (InputStream, Reader, Writer) instead of concrete files makes them easy to test: in production you pass a file stream, and in tests a StringReader with sample data.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. in.read() on an InputStream returns -1. What does that mean?

    read() returns data bytes as 0 to 255, so -1 is free to mean end of stream. A byte with all bits set comes back as 255.
  2. 2. A program writes a report through a BufferedWriter but never closes or flushes it. What is the likely result?

    Buffered output stays in memory until the buffer fills, flush() is called or the stream is closed. try-with-resources closes it reliably.
  3. 3. You have a socket's InputStream and want to read lines of UTF-8 text. What do you write?

    InputStreamReader bridges bytes to characters with a charset, and BufferedReader adds buffering and readLine().
  4. 4. int n = in.read(buffer) returns 5 for a 1024-byte buffer. Which bytes are valid?

    read(buffer) fills from index 0 and returns how many bytes it stored. Only buffer[0] to buffer[n - 1] are new data.
  5. 5. Why can writing a file with PrintWriter fail without you noticing?

    PrintWriter and PrintStream record errors internally instead of throwing. checkError() flushes and reports whether any write failed.

Summary

  • Byte streams (InputStream/OutputStream) move raw bytes; character streams (Reader/Writer) move text and convert with a charset.
  • read() returns 0โ€“255 or -1 at the end; read(buffer) returns how many bytes it filled. readAllBytes, readNBytes and transferTo handle common loops.
  • Wrap streams to add features: Buffered* for speed, InputStreamReader/OutputStreamWriter to bridge bytes and text, PrintWriter for formatting, Data*Stream for binary primitives.
  • Buffered output must be flushed or closed; close every stream with try-with-resources, and know that closing a wrapper closes what it wraps.
  • BufferedReader.readLine() in a while (... != null) loop reads any text source line by line.
  • PrintWriter hides errors; check checkError() or use BufferedWriter when correctness matters.

Next: Working with Directories, where you'll list, search and walk folder trees and read file attributes.