Reading files

In Scanner and console applicationsyour programs read what a person typed at the keyboard. Most of the data a program needs is not typed live, though. It is already on disk in a file: a list of names, yesterday's sales, a saved game. This lesson is about opening such a file and reading it, one line at a time.

Why read from a file at all?#

A Scanner on the keyboard is fine when a person is there to answer. Now think about a program that prints a report from ten thousand sales records. Nobody is going to type ten thousand numbers. Those records live in a file, written there earlier, perhaps by another program. Reading from a file lets your program work with data that already exists and that outlives any single run.

A plain text file is a sequence of characters, with line break marks splitting it into lines. When you open notes.txtin an editor and see three lines, the file on disk is one long ribbon of characters with invisible “new line” marks in it. Reading the file means walking along that ribbon from the start to the end.

FileReader and BufferedReader#

To read a text file in Java you typically use two classes stacked together. A FileReader knows how to open one named file and pull characters out of it. A BufferedReader wraps around a FileReader and adds two things: it reads the file in large chunks, which is faster, and it has a method that hands back a whole line at a time. You wrap one inside the other:

Buy milk
Walk the dog
Call Maya

Read the wrapping out loud: “a buffered reader, reading from a file reader, reading from notes.txt”. The FileReader is the part touching the disk. The BufferedReader is the friendly layer on top that you talk to, and its readLine() hands back the first line, Buy milk. Two pieces of this program are explained further down the page: throws IOException on the line that declares main, and the br.close() at the end. Until then, copy them as they are.

People usually fold the two lines that build the readers into one: BufferedReader br = new BufferedReader(new FileReader("notes.txt"));. The rest of this page writes it that way.

Reading line by line with readLine()#

The method you call on a BufferedReader is readLine(). Each call returns the next line of the file as a String, without the line break at its end. Call it again and you get the line after that. When there are no more lines, readLine() returns null. That nullis the file's way of saying “there is nothing left”. This point is the end of file, often shortened to EOF.

Key idea

readLine() gives you the next line as a String, or null when the file is used up. That null is your signal to stop reading.

Calling readLine() four times on a three-line file makes this concrete. The file notes.txt holds exactly the three lines shown under the code:

Buy milk
Walk the dog
Call Maya

The first three calls hand back the three lines. The fourth call has nothing left to give, so it returns null, and printing null shows the word null. Step through it and read the narration on the fourth call: it says the reader has reached the end of the file.

Why you must close a file#

When you open a file, the operating system hands your program a kind of ticket: a live connection to that file, called a file handle. The system has only a limited number of these tickets. If you open files and never give the tickets back, your program leaks them, and eventually the system refuses to open any more. Closing a reader returns the ticket. close()is how you say “I am done with this file”.

Closing matters for a second reason, and it bites harder when writing than reading: a buffer may still hold data that has not been pushed all the way to the file. Closing flushes it out, and writing files shows what happens without it. The habit to build is simple: if you open it, close it.

try-with-resources: closing that cannot be skipped#

Java has a dedicated shape for “use this thing, then close it no matter what”. It is called try-with-resources. You declare the reader inside parentheses right after the word try, and Java closes the reader for you when the block ends, whether the block finishes normally or something fails partway through.

Buy milk
Walk the dog
Call Maya

Look closely at the first line of the try. The reader is created inside the parentheses try ( ... ), not inside the body. That placement tells Java “this is a resource I am borrowing; close it the moment this block is done”. You write no close() yourself, so there is no way to forget it and no way for a failure to skip it. Step through the program: just before Done reading. prints, the narration says that br is closed automatically.

1. 1Java runs the part in parentheses, opening the file and building br.
2. 2Java runs the body of the try, where you read from br.
3. 3When the body ends, for any reason, Java calls br.close() for you.

Key idea

Declare a reader inside try ( ... ) and Java closes it for you when the block ends, however it ends. Use this shape for every file you open.

Files can fail: IOException#

Reading the keyboard rarely surprises you. Reading a file is different, because the file lives outside your program and outside your control. The file might not exist. It might exist, but you might not have permission to read it. The disk might be unplugged in the middle of a read. Java does not let you pretend these cannot happen. Any operation that touches a file is allowed to fail with an IOException, where IO stands for input and output.

Here is what a missing file looks like. The disk holds notes.txt, but the program asks for notez.txt, a typo:

Buy milk
Walk the dog
Call Maya

The program prints its first line, then stops on line 8 with java.io.FileNotFoundException: notez.txt (No such file or directory). FileNotFoundException is one kind of IOException: the kind for a file that cannot be opened. The text in brackets comes from the operating system, so on Windows it reads (The system cannot find the file specified) instead.

Because files can fail, Java makes you acknowledge it. Every program on this page has the same small piece on the line that declares main: throws IOException. Those words are a label on the method. They say “the code inside might run into an input or output problem, and this method is not dealing with it here; it passes the problem on to whoever called it”. For main, that means the program stops with a report, as it just did. Writing throws IOException on main is enough to make a file-reading program compile and run. You also need the import import java.io.IOException; at the top, so Java knows what that name means.

Reading the whole file: a loop that counts lines#

In practice you almost never want exactly three lines. You want every line, however many there are, and the file decides how many. That is a loop, and the stopping condition is the null from readLine(). The classic pattern reads a line, checks it against null, and enters the loop body only if there really was a line:

Buy milk
Walk the dog
Call Maya

Walk through it with the same three-line notes.txt. Before the loop, line is set to the first line, "Buy milk". The loop checks: not null, so enter. count becomes 1. "Buy milk" is 8 characters, not more than 10, so nothing prints. Then the last line of the body reads the next line, "Walk the dog". Loop again: not null, count becomes 2, and "Walk the dog" is 12 characters, more than 10, so it prints. Read again: "Call Maya". Loop: count becomes 3, 9 characters, no print. Read again: null. The loop condition is now false, so the program leaves the loop and prints the count, 3.

It prints Walk the dog and then null. The test in the while reads Buy milk and throws it away, and the println reads the next line, Walk the dog. On the second pass the test uses up Call Maya, so the println finds the end of the file and prints null. Then the test gets null and the loop stops.

Turning lines into data#

A line from a file is always a String, even when it looks like a number. To do arithmetic with it, cut it into pieces and convert the pieces. Suppose scores.txt holds a name and a score on each line. split(" "), which you used to count words in HashMap and HashSet, cuts each line at the space into an array, and Integer.parseInt turns the score into an int:

Ada 91
Grace 88
Alan 79

For the line Ada 91, split gives the array ["Ada", "91"]. parts[0] is the name and parts[1] is the text "91", which parseInt turns into the number 91. Without that step, "91" + 1 would join text and give "911". The three scores add up to 258, and the cast to double makes the division keep its fraction, so the program prints Average: 86.0.

1import java.io.BufferedReader;
2import java.io.FileReader;
3import java.io.FileWriter;
4import java.io.IOException;
5 
6public class Main {
7    public static void main(String[] args) throws IOException {
8        // Make the file to read. Writing files is the next session.
9        FileWriter setup = new FileWriter("basket.txt");
10        setup.write("apples 120\nbread 250\nmilk 95\n");
11        setup.close();
12 
13        int total = 0;
14        // TODO: read basket.txt line by line, split each line at the space,
15        // and add each price to total
16 
17        System.out.println("Total: " + total + " cents");
18    }
19}

Reading a file with a Scanner#

A Scanner can read a file as well as the keyboard. Give it a File instead of System.in, and every method from the Scanner lesson works on the file's text: next(), nextInt(), nextLine() and the hasNext family. The input runs out at the end of the file, so hasNext() makes a natural loop condition:

Ada 91
Grace 88
Alan 79

next() reads the name and nextInt() reads the score, so there is no split and no parseInt. A Scanner on a file is closed with try-with-resources in the same way, and new Scanner(new File(...)) throws a FileNotFoundException when the file is missing, so main still says throws IOException. Use a BufferedReader when you want whole lines, and a Scanner when the file is a series of words and numbers you want one at a time.

The shape to remember#

Strip away the example and a file-reading program makes the same four moves every time.

• Open the file in a try ( ... ) so it closes itself: new BufferedReader(new FileReader(name)).
• Loop, calling readLine(), doing something with each line.
• Stop when readLine() returns null, the end of the file.
• Let the method say throws IOException, because file work can fail.

That pattern reads a settings file, a list of names, a log or a saved score table: anything that is text, one record per line. From one program to the next, only the work inside the loop changes.

Further reading#

• BufferedReader in the Java SE 25 API documentation, with readLine and why wrapping a FileReader helps
• FileReader in the Java SE 25 API documentation, including the exceptions its constructors throw
• The try-with-resources statement in the Java Language Specification, section 14.20.3