Try-with-resources in Java

The classic try-finally pattern has a hidden flaw: if br.readLine() throws an IOException and then br.close() in the finally block fails as well, only the exception from close() leaves the method — the real cause of the failure disappears without a trace. The try-with-resources statement fixes this problem, together with the problem of a forgotten close() call.

Try-with-resources is a form of the Java try statement (introduced in Java 7) in which resources are declared in parentheses after try and closed automatically: close() is called when the try block exits, both on normal completion and when an exception is thrown. A resource can be any object whose class implements java.lang.AutoCloseable (including its subinterface java.io.Closeable): I/O streams, sockets, JDBC connections, Scanner.

Try-with-resources syntax

A resource is declared and initialised in parentheses right after the try keyword; several resources are separated by semicolons. The catch and finally blocks are optional: if the checked exceptions are declared in the method’s throws clause, a bare try block is enough.

try (ResourceType1 name1 = new ResourceType1(...);
     ResourceType2 name2 = new ResourceType2(...)) {
    // work with the resources
} catch (IOException e) {
    // optional
} finally {
    // optional
}

A resource variable is implicitly final and is visible only inside the try block: it is out of scope in catch and finally, and by then the resource is already closed. If you need a refresher on plain try, catch and finally, see Java Try Catch Finally; its short try-with-resources section is the starting point for this lesson. The formal rules are in JLS §14.20.3.

try-finally vs try-with-resources

Before Java 7 a resource was closed by hand in a finally block; try-with-resources does the same automatically, with less code and more safety: there is no close() call to forget, and an exception from close() no longer overwrites the original one. Compare two versions of a method that reads the first line of a file (imports java.io.*).

Example 1. Closing a resource in finally

public static String readFirstLineWithFinally(String path) throws IOException {
    BufferedReader br = new BufferedReader(new FileReader(path));
    try {
        return br.readLine();
    } finally {
        br.close();
    }
}

A br != null check is not needed here: if the file does not exist, new FileReader(path) throws FileNotFoundException before the try block is entered, and the variable is never assigned.

Now the same method rewritten with try-with-resources.

Example 2. The same method with try-with-resources

public static String readFirstLine(String path) throws IOException {
    try (BufferedReader br = new BufferedReader(new FileReader(path))) {
        return br.readLine();
    }
}

// The file a.txt contains the lines "Hello" and "World":
// readFirstLine("a.txt")       -> "Hello"
// readFirstLine("missing.txt") -> java.io.FileNotFoundException

Multiple resources and closing order

A single try-with-resources statement can declare several resources separated by semicolons; they are opened from left to right and closed in reverse order — the last one opened is closed first. If the constructor of the second resource throws an exception, the first resource, which is already open, is still closed.

Example 3. Two resources in one try

public static String readFirstLine2(String path) throws IOException {
    try (FileReader fr = new FileReader(path);
         BufferedReader br = new BufferedReader(fr)) {
        return br.readLine();
    }
}

br is closed first, then fr. BufferedReader.close() already closes the wrapped FileReader, so the second close() on fr does nothing — this is safe, because closing a Closeable that is already closed must have no effect.

The order is easy to see with a custom resource that prints a message when it is opened and closed.

Example 4. Opening and closing order

public class CloseOrderDemo {

    static class Resource implements AutoCloseable {
        private final String name;

        Resource(String name) {
            this.name = name;
            System.out.println("Opened " + name);
        }

        @Override
        public void close() {
            System.out.println("Closed " + name);
        }
    }

    public static void main(String[] args) {
        try (Resource a = new Resource("A");
             Resource b = new Resource("B")) {
            System.out.println("Working with resources");
        }
    }
}

// Output:
// Opened A
// Opened B
// Working with resources
// Closed B
// Closed A

Note that close() here is declared without throws Exception, so no catch block is required. If close() threw a checked exception, the compiler would demand that you handle it or declare it in throws (the difference between checked and unchecked exceptions is explained in Exceptions in Java).

AutoCloseable vs Closeable: what can be a resource

Only an object whose class implements java.lang.AutoCloseable can be a resource in try-with-resources. java.io.Closeable extends AutoCloseable, so every I/O stream from java.io qualifies automatically. The two interfaces differ in the signature of close() and in what is required from it.

When you write your own resource, narrow the exception in close(): declare throws IOException, a custom exception class, or no checked exception at all, as in Example 4. Then the calling code does not have to catch a generic Exception. See the AutoCloseable Javadoc for the full contract.

Suppressed exceptions and getSuppressed()

If the try block throws an exception and then close() throws too, the exception from the try block propagates, and the exception from close() is attached to it with addSuppressed(). The suppressed exceptions are returned by Throwable.getSuppressed() as a Throwable[] array (both methods were added to Throwable in Java 7).

Example 5. What does this code print?

public class SuppressedDemo {

    static class FaultyResource implements AutoCloseable {
        @Override
        public void close() {
            throw new IllegalStateException("error in close()");
        }
    }

    public static void main(String[] args) {
        // Option 1: try-finally
        try {
            FaultyResource r = new FaultyResource();
            try {
                throw new RuntimeException("error in try block");
            } finally {
                r.close();
            }
        } catch (RuntimeException e) {
            System.out.println("finally: " + e.getMessage()
                    + ", suppressed: " + e.getSuppressed().length);
        }

        // Option 2: try-with-resources
        try (FaultyResource r = new FaultyResource()) {
            throw new RuntimeException("error in try block");
        } catch (RuntimeException e) {
            System.out.println("try-with-resources: " + e.getMessage());
            for (Throwable s : e.getSuppressed()) {
                System.out.println("  suppressed: " + s.getMessage());
            }
        }
    }
}

// Output:
// finally: error in close(), suppressed: 0
// try-with-resources: error in try block
//   suppressed: error in close()

In the finally version the original exception “error in try block” is gone completely — which is why debugging such code turns into a hunt for an error that “does not exist”. Try-with-resources keeps both errors.

catch and finally in try-with-resources

In try-with-resources the catch and finally blocks run after all resources have been closed. So you cannot use the resource in catch to “rescue” data, and an exception thrown while closing can be caught by that same catch.

Example 6. Execution order

// Resource is the class from Example 4
try (Resource r = new Resource("R")) {
    throw new IllegalArgumentException("failure");
} catch (IllegalArgumentException e) {
    System.out.println("catch: " + e.getMessage());
} finally {
    System.out.println("finally");
}

// Output:
// Opened R
// Closed R
// catch: failure
// finally

If the exception is thrown while the resource is being created (for example, FileNotFoundException in the FileReader constructor), the body of the try block does not run, there is nothing to close, and control goes straight to the matching catch.

Java 9: a resource declared before try

Since Java 9 the parentheses of try-with-resources can hold an existing variable, as long as it is final or effectively final (nothing is assigned to it after initialisation). In Java 7 and 8 the resource had to be declared inside the parentheses, even if the object already existed.

// Java 7/8: a new variable was required
public static String readFirstLine(BufferedReader reader) throws IOException {
    try (BufferedReader br = reader) {
        return br.readLine();
    }
}

// Java 9+: the variable itself is enough
public static String readFirstLine9(BufferedReader reader) throws IOException {
    try (reader) {
        return reader.readLine();
    }
}

If the variable is reassigned anywhere in the method, try (reader) does not compile: the variable is no longer effectively final. Apart from this change, try-with-resources has behaved the same way in every release since Java 7.

Common mistakes

Most mistakes with try-with-resources come from the scope of the resource variable, from wrapper streams and from resources that should not be closed at all. The table shows what happens in each case and how to fix it.