Reading files

java.nio.file.Files has a method for each size of job: one for a whole text file, one for its lines, and one for a stream that never holds more than a line at a time. Every program of this lesson writes the file it reads first, so it runs on its own, and every one names its charset instead of trusting the platform default.

readString and readAllLines

The program writes three lines, reads the file as one string, then as a list of lines:

import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.util.List; public class ReadAll { public static void main(String[] args) throws IOException { Path file = Path.of("notes.txt"); Files.writeString(file, "first line\nsecond line\nthird line\n", StandardCharsets.UTF_8); String text = Files.readString(file, StandardCharsets.UTF_8); System.out.println("characters: " + text.length()); System.out.println("lines: " + text.lines().count()); List<String> lines = Files.readAllLines(file, StandardCharsets.UTF_8); for (int i = 0; i < lines.size(); i++) { System.out.println((i + 1) + ": " + lines.get(i)); } Files.delete(file); System.out.println("deleted: " + !Files.exists(file)); } }

javac -Xlint:all ReadAll.java
java ReadAll

characters: 34
lines: 3
1: first line
2: second line
3: third line
deleted: true

The character count includes the three line separators, because a string of a text file is the bytes decoded and nothing is removed: 10 + 11 + 10 characters plus three newlines is 34. text.lines() answers a stream of the three lines without counting the final separator as an extra empty line.

readAllLines splits for you and returns a list a program can index. Both methods answer a value and throw IOException, which main declares here; a library method would wrap it as lesson 099 showed.

Files.lines

Files.lines answers a Stream of lines that is read as the pipeline asks for them, so the file is never held whole. The stream holds a file handle, and that is why it is closed, with try-with-resources of lesson 098:

import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.NoSuchFileException; import java.nio.file.Path; import java.util.List; public class Lines { public static void main(String[] args) throws IOException { Path file = Path.of("words.txt"); Files.write(file, List.of("alpha beta", "gamma", "delta epsilon zeta"), StandardCharsets.UTF_8); try (var stream = Files.lines(file, StandardCharsets.UTF_8)) { long words = stream.flatMap(line -> java.util.Arrays.stream(line.split(" "))).count(); System.out.println("words: " + words); } long lengths = 0; try (var stream = Files.lines(file, StandardCharsets.UTF_8)) { lengths = stream.mapToLong(String::length).sum(); } System.out.println("characters in lines: " + lengths); try { Files.readAllLines(Path.of("missing.txt"), StandardCharsets.UTF_8); } catch (NoSuchFileException e) { System.out.println("missing: " + e.getFile()); } Files.delete(file); } }

javac -Xlint:all Lines.java
java Lines

words: 6
characters in lines: 33
missing: missing.txt

Two words on the first line, one on the second and three on the third is six, and the character count of 10 + 5 + 18 is 33 without the separators, because String.length of a line does not count the newline that was removed. The stream is opened twice, once per pass, because a stream is read once (lesson 092).

A file that is not there

The third line of the output is the exception of a missing file. NoSuchFileException extends FileSystemException and carries the path, which is what getFile prints; the message of the class is the path alone, so a report that prints the message reads the same. A program that treats a missing file as a normal case catches it, and one that cannot work without the file lets it travel.

The other exceptions of the same family are AccessDeniedException for a permission and FileSystemException for the rest, and all of them are IOException, so a catch of the parent covers them. That is the one place a broad catch is right: the caller of a read cannot do anything different about the four kinds.

A file too big to hold

The stream is the answer when the file does not fit in memory. The program writes a thousand lines, counts them, and finds the last one without ever building a list of all of them:

import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; public class Big { public static void main(String[] args) throws IOException { Path file = Path.of("big.txt"); StringBuilder builder = new StringBuilder(); for (int i = 0; i < 1000; i++) { builder.append("line ").append(i).append('\n'); } Files.writeString(file, builder.toString(), StandardCharsets.UTF_8); System.out.println("bytes: " + Files.size(file)); try (var stream = Files.lines(file, StandardCharsets.UTF_8)) { System.out.println("lines: " + stream.count()); } try (var stream = Files.lines(file, StandardCharsets.UTF_8)) { System.out.println("last: " + stream.reduce((a, b) -> b).orElse("")); } Files.delete(file); } }

javac -Xlint:all Big.java
java Big

bytes: 8890
lines: 1000
last: line 999

The size is 8890 bytes and every character is one byte in UTF-8: five for line a thousand times, the digits of the numbers, and one newline per line. The reduce keeps only the last line of the stream, which is how a program reads the tail of a file of any size.

Which method to use

readString for a small file that is wanted whole, such as a configuration or a template. readAllLines for a small file whose lines are wanted by index. Files.lines for anything large or of unknown size, and for a pipeline: it is the only one of the three that does not load the file. A charset is always given, and StandardCharsets.UTF_8 is the answer unless the file comes from somewhere else, which is lesson 109.

The scanner of lesson 104 is the fourth option, for a file of tokens of known types, and it is the one to avoid for a big file because its buffering is hidden. A BufferedReader is the classic form of the stream, and Files.newBufferedReader returns one when the code wants readLine and a loop rather than a pipeline.

Exercises

  1. Read a file of numbers and print the largest with a stream.
  2. Count the lines of a file that are longer than twenty characters.
  3. Print the first three lines of a file with limit.
  4. Catch IOException around a read of a directory and print the class of the exception.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which method reads a whole file as one string?

    Answer

    Files.readString with a charset

    readString decodes the bytes into one string, and the charset decides how.

  2. Why must a stream from Files.lines be closed?

    Answer

    It holds an open file handle

    The stream reads from an open file, so the handle is released by close.

  3. Which exception does a missing file give?

    Answer

    NoSuchFileException, a subclass of IOException

    The nio file API throws NoSuchFileException, which carries the path.

  4. What does this program print? import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; public class Q1 { public static void main(String[] args) throws IOException { Path file = Path.of("t.txt"); Files.writeString(file, "a\nbb\nccc", StandardCharsets.UTF_8); System.out.println(Files.readAllLines(file, StandardCharsets.UTF_8).size()); System.out.println(Files.readString(file, StandardCharsets.UTF_8).length()); Files.delete(file); } }

    Answer

    3 / 8

    Three lines, and the string is their eight characters with the two separators between them.

  5. Why is Files.lines the choice for a large file?

    Answer

    It reads one line at a time, so the file is never held whole

    The stream pulls a line when the pipeline asks, which is what keeps the memory small.

  6. What does text.lines() answer for a text that ends with a newline?

    Answer

    A stream of the lines, with no empty line for the final separator

    The final separator ends the last line and does not start another.

  7. Why does every program of the lesson write the file it reads?

    Answer

    So the program runs alone and the output on the page is the real one

    A whole program that creates its input can be built and run by the checker with no setup.

  8. What does this program print? import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; public class Q2 { public static void main(String[] args) throws IOException { Path file = Path.of("u.txt"); Files.write(file, java.util.List.of("one", "two", "three"), StandardCharsets.UTF_8); System.out.println(Files.readAllLines(file, StandardCharsets.UTF_8).get(2)); System.out.println(Files.size(file)); Files.delete(file); } }

    Answer

    three / 14

    The lines are one, two and three, and the file is 14 bytes with a separator after each line.

  9. What does this program print when the file does not exist? import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.NoSuchFileException; import java.nio.file.Path; public class Q3 { public static void main(String[] args) throws IOException { try { Files.readString(Path.of("absent.txt"), StandardCharsets.UTF_8); } catch (NoSuchFileException e) { System.out.println("no file: " + e.getFile()); } } }

    Answer

    no file: absent.txt

    The exception carries the path it was given, and the catch prints it.

  10. Which charset should a new program name for a text file?

    Answer

    StandardCharsets.UTF_8, unless the file comes from another system

    The default depends on the machine, and UTF-8 is the one that is the same everywhere.

The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.

Article author: Arthur Isaev