File I/O: reading and writing files in Java

A notebook in a drawer#

Using a file is like using a notebook kept in a drawer. You open the drawer and take the notebook out. You read it from the first page onwards, or you write in it. Then you close it and put it back. Skip that last step and someone who comes to read it later may find your last notes were never really written down.

Java works through streams. A stream is a flow of data in one direction, like water through a hose: an input stream flows from the file into your program, an output stream flows from your program into the file. The data comes in order, from the start; you do not jump around.

The classes live in two packages, so file programs usually start with imports from java.io (File, FileWriter, PrintWriter, FileReader, BufferedReader, IOException) and java.util (Scanner).

Writing to a file#

The friendliest way to write text is a PrintWriter. It has the same print, println and printf you already use with System.out, but the text goes into a file. Wrap it around a FileWriter, which does the actual opening:

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Scanner;

public class Write {
    public static void main(String[] args) throws IOException {
        PrintWriter out = new PrintWriter(new FileWriter("scores.txt"));
        out.println("Ana,91");
        out.println("Ben,78");
        out.printf("%s,%d%n", "Cy", 85);
        out.close();

        PrintWriter more = new PrintWriter(new FileWriter("scores.txt", true));
        more.println("Dee,99");
        more.close();

        Scanner check = new Scanner(new File("scores.txt"));
        while (check.hasNextLine()) {
            System.out.println(check.nextLine());
        }
        check.close();
    }
}

Ana,91
Ben,78
Cy,85
Dee,99

Opening scores.txt created it, because it did not exist yet. If it had existed, it would have been emptied first: a plain FileWriter overwrites. To add to the end instead, pass true as a second argument, new FileWriter("scores.txt", true), which means “append”.

Notice throws IOException on main. Opening a file can fail (a full disk, a folder you may not write to), and IOException is a checked exception, so the compiler insists you either catch it or declare it. Declaring it keeps these first listings short; handling it properly comes below.

Closing a file, and why it matters#

Writers keep text in a buffer, a small holding area in memory, and send it to the disk in batches because each trip to the disk is slow. close() sends whatever is still waiting, then releases the file. Forget it, and the last batch, which for a small file is everything, may never arrive:

import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Scanner;

public class NoClose {
    static int linesIn(String name) throws FileNotFoundException {
        Scanner in = new Scanner(new File(name));
        int n = 0;
        while (in.hasNextLine()) {
            in.nextLine();
            n++;
        }
        in.close();
        return n;
    }

    public static void main(String[] args) throws IOException {
        PrintWriter out = new PrintWriter(new FileWriter("notes.txt"));
        out.println("first line");
        out.println("second line");
        out.println("third line");
        System.out.println("Lines in the file before close: " + linesIn("notes.txt"));
        out.close();
        System.out.println("Lines in the file after close:  " + linesIn("notes.txt"));
    }
}

Lines in the file before close: 0
Lines in the file after close:  3

The program wrote three lines, yet before close() the file holds none of them: they were still sitting in the buffer. After close() all three are there. Closing also releases the file so other programs can use it. The modern way to make sure a file is always closed, even if an exception happens halfway through, is try-with-resources: open the file in brackets right after try, and Java closes it automatically when the block ends.

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Scanner;

public class Resources {
    public static void main(String[] args) throws IOException {
        try (PrintWriter out = new PrintWriter(new FileWriter("log.txt"))) {
            for (int i = 1; i <= 3; i++) {
                out.println("entry " + i);
            }
        }
        try (Scanner in = new Scanner(new File("log.txt"))) {
            while (in.hasNextLine()) {
                System.out.println("read back: " + in.nextLine());
            }
        }
    }
}

read back: entry 1
read back: entry 2
read back: entry 3

No close() call, and the file was closed anyway, which is why the second block could read all three entries back. The reading Scanner is closed the same way. This is the one form of try that may stand alone without catch or finally.

Reading with Scanner#

You already know Scanner from reading the keyboard. Point it at a File object instead of System.in and it reads the file with the same methods: nextLine, nextInt, next, and the hasNext... methods that ask whether anything is left.

The file scores.txt holds:

Ana,91
Ben,78
Cy,85
Dee,99

import java.io.File;
import java.io.FileNotFoundException;
import java.util.Scanner;

public class ReadScanner {
    public static void main(String[] args) throws FileNotFoundException {
        Scanner in = new Scanner(new File("scores.txt"));
        int count = 0, total = 0;
        while (in.hasNextLine()) {
            String line = in.nextLine();
            String[] parts = line.split(",");
            int score = Integer.parseInt(parts[1]);
            System.out.println(parts[0] + " scored " + score);
            count++;
            total += score;
        }
        in.close();
        System.out.println("Average of " + count + ": " + (double) total / count);
    }
}

Ana scored 91
Ben scored 78
Cy scored 85
Dee scored 99
Average of 4: 88.25

The loop pattern is the one to memorise: while hasNextLine(), call nextLine(). Inside, split(",") breaks the line at each comma into an array of pieces, and Integer.parseInt turns the text "91" into the number 91.

When a file is just numbers or words separated by spaces, hasNextInt() and nextInt() read one token (one piece between spaces or line breaks) at a time, with no splitting needed. The same nextInt-then-nextLine leftover-newline trap from keyboard input applies to files too.

Now the trap that catches nearly everyone once:

The file data.txt holds:

42

import java.util.Scanner;

public class ScanTrap {
    public static void main(String[] args) {
        Scanner in = new Scanner("data.txt");
        System.out.println(in.nextLine());
    }
}

data.txt

new Scanner("data.txt") is not a file. It is a Scanner reading the String "data.txt", eight characters long. It happily returns those characters, and never looks at the real data.txt or the 42 inside it. To read the file, you must wrap the name in a File object: new Scanner(new File("data.txt")).

Reading with BufferedReader#

BufferedReader is the other common way to read text. Wrap it around a FileReader. It has one main method, readLine(), which returns the next line, or null when the file has run out:

The file poem.txt holds:

Roses are red

Violets are blue
Files must be closed

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;

public class ReadBuffered {
    public static void main(String[] args) throws IOException {
        BufferedReader in = new BufferedReader(new FileReader("poem.txt"));
        String line;
        int number = 0, blank = 0;
        while ((line = in.readLine()) != null) {
            number++;
            if (line.isEmpty()) {
                blank++;
            } else {
                System.out.println(number + ": " + line);
            }
        }
        in.close();
        System.out.println(number + " lines, " + blank + " blank");
    }
}

1: Roses are red
3: Violets are blue
4: Files must be closed
4 lines, 1 blank

The loop reads a line into line and checks it for null in one go: while ((line = in.readLine()) != null). The extra brackets make the assignment happen first. This is the standard BufferedReader loop, worth recognising on sight.

Scanner or BufferedReader: which and why#

The “buffered” in BufferedReader is the point. It pulls a large block of the file into memory at a time, 8,192 characters by default, and hands you lines from that block, so it makes few slow trips to the disk. Scanner also buffers, but it spends extra work breaking text into tokens and checking their types.

Use Scanner for small files, and whenever the content is a mix of words and numbers you want converted as you read. Do not use it for very large files, where its speed hurts, or when you need to know that a read failed. Use BufferedReader for large files and line-by-line processing, accepting that you will convert the numbers yourself.

Handling file exceptions#

File operations throw checked exceptions, so the compiler will not let you ignore them. The two to know are FileNotFoundException, when the file to read does not exist (or cannot be opened), and its parent IOException, for anything else that goes wrong while reading or writing.

import java.io.File;
import java.io.FileNotFoundException;
import java.util.Scanner;

public class Missing {
    public static int countLines(String name) {
        int count = 0;
        try (Scanner in = new Scanner(new File(name))) {
            while (in.hasNextLine()) {
                in.nextLine();
                count++;
            }
        } catch (FileNotFoundException e) {
            System.out.println("Could not open " + name + ", counting 0 lines");
        }
        return count;
    }

    public static void main(String[] args) {
        System.out.println(countLines("missing.txt"));
        System.out.println("The program is still running");
        System.out.println(new File("missing.txt").exists());
    }
}

Could not open missing.txt, counting 0 lines
0
The program is still running
false

The program did not crash: the catch turned a missing file into a clear message, and execution carried on. When a block can throw both file exceptions, the exceptions guide’s rule applies: catch FileNotFoundException, the child, before IOException, its parent. (The text of e.getMessage() differs between Windows and other systems, which is why this listing prints its own message.)

A file the program insists is missing, while you can see it in the folder, is nearly always a path problem. A bare name like "data.txt" is a relative path: Java looks for it in the program’s working directory, the folder the program was started from. In BlueJ and VS Code that is normally the project folder, not the src folder. new File("data.txt").getAbsolutePath() prints exactly where Java is looking, and exists() tells you whether anything is there.

Where these go wrong#

• Never closing a writer. The buffered text may never reach the disk, leaving an empty file.
• new Scanner("data.txt"). That reads the String itself. Write new Scanner(new File("data.txt")).
• Opening an existing file with new FileWriter(name) when you meant to add to it. It is emptied first. Use new FileWriter(name, true).
• Forgetting the checked exceptions. Without a catch or a throws clause the code does not compile.
• Catching IOException before FileNotFoundException. The child must come first or the second catch is unreachable.
• Testing readLine() for an empty String to find the end. An empty line is ""; the end of the file is null.
• Putting the data file in the src folder. A relative path is looked up from the working directory, usually the project folder.

Practice#

Answer each one on paper before you look at the solutions. Every answer that involves running code was checked by compiling and running it.

1. What is the difference between new FileWriter("log.txt") and new FileWriter("log.txt", true) when log.txt already has text in it?
2. A program writes three lines with a PrintWriter, never calls close(), and the file comes out empty. Explain why, and give two fixes.
3. A file numbers.txt holds whole numbers separated by spaces and line breaks. Write a program that prints their sum, handling a missing file.
4. Give one situation where Scanner is the better choice and one where BufferedReader is, with the reason.
5. Write a program that copies in.txt to out.txt with every line in capitals, using BufferedReader and PrintWriter.
6. Your program throws FileNotFoundException for data.txt, but you can see the file in your project. What is the likely cause, and what one line would show you?

Solutions#

1. The first empties the file and starts writing from the beginning. The second opens it in append mode, so new text is added after what is already there.
2. A PrintWriter holds text in a buffer and sends it to the disk in batches; the batch was never sent because the writer was never closed (or flushed). Fixes: call out.close() when finished, or open the writer with try-with-resources so it is closed automatically.
3. Read token by token with hasNextInt and nextInt; for a file holding 4 8 15 16 23 42:

   The file numbers.txt holds:

   4 8
   15 16
   23 42

   import java.io.File;
   import java.io.FileNotFoundException;
   import java.util.Scanner;
   
   public class QSum {
       public static void main(String[] args) {
           int sum = 0;
           try (Scanner in = new Scanner(new File("numbers.txt"))) {
               while (in.hasNextInt()) {
                   sum += in.nextInt();
               }
           } catch (FileNotFoundException e) {
               System.out.println("numbers.txt is missing");
           }
           System.out.println("Sum: " + sum);
       }
   }

   Sum: 108

4. Scanner: a small file mixing words and numbers, because it converts tokens as it reads. BufferedReader: a very large log file processed line by line, because it reads big blocks at a time and is faster, and it reports read errors as IOException instead of hiding them.
5. Both files open in one try-with-resources, separated by a semicolon, so both are closed automatically:

   The file in.txt holds:

   one
   two
   three

   import java.io.BufferedReader;
   import java.io.FileReader;
   import java.io.FileWriter;
   import java.io.IOException;
   import java.io.PrintWriter;
   
   public class QCopy {
       public static void main(String[] args) {
           try (BufferedReader in = new BufferedReader(new FileReader("in.txt"));
                PrintWriter out = new PrintWriter(new FileWriter("out.txt"))) {
               String line;
               while ((line = in.readLine()) != null) {
                   out.println(line.toUpperCase());
               }
           } catch (IOException e) {
               System.out.println("Copy failed: " + e.getMessage());
           }
   
           try (BufferedReader check = new BufferedReader(new FileReader("out.txt"))) {
               String line;
               while ((line = check.readLine()) != null) {
                   System.out.println(line);
               }
           } catch (IOException e) {
               System.out.println("Could not read the copy");
           }
       }
   }

   ONE
   TWO
   THREE

6. The relative path is being looked up from the working directory, and the file is somewhere else, such as inside src. System.out.println(new File("data.txt").getAbsolutePath()); prints the exact location Java is checking.

Test-readiness checklist#

These are the items from the course’s Exam 2 topic list that this guide covers. Tick each one only when you can do it without looking.

• ☐  I can open a file for writing and for reading, and explain what a stream is.
• ☐  I can write to a file with PrintWriter and FileWriter, including appending.
• ☐  I can read from a file with Scanner and with BufferedReader, and explain why to use BufferedReader.
• ☐  I can say when to use the Scanner class and when not to.
• ☐  I can close a file, and explain why closing matters, including try-with-resources.
• ☐  I can handle file exceptions: FileNotFoundException and IOException.

Frequently asked questions#

Something here not clear? A topic you wish we covered? Tell us. We read every message, and a request is the fastest way to get a guide written — several of these exist because somebody asked.