try-with-resources

Written Explanation

The old way: finally plus close

Here is how code had to close a file by hand:

static String firstLine(String path) throws IOException {
    BufferedReader reader = null;
    try {
        reader = Files.newBufferedReader(Path.of(path));
        return reader.readLine();
    } finally {
        if (reader != null) {
            reader.close();
        }
    }
}

It works, but it is clumsy: the variable must be declared outside the try, set to null, and checked again in finally. Worse, close() can itself throw an exception. The Oracle tutorial explains the trap: if both readLine and close throw, the exception from finally replaces the one from the try, so the original problem is lost. With several resources, one failing close() can even stop the next from being closed.

The new way

Put the resource in parentheses after try:

static String firstLine(String path) throws IOException {
    try (BufferedReader reader = Files.newBufferedReader(Path.of(path))) {
        return reader.readLine();
    }
}

When the block ends, Java calls close() for you, whether the block finished normally, threw an exception, or left with return. The Oracle tutorial describes it as closing each resource when the statement ends, normally or abruptly. There is no null check, no finally, and the variable reader exists only inside the statement, so nobody can use it after it is closed.

What counts as a resource: AutoCloseable

A resource is any object whose class implements the interface java.lang.AutoCloseable, which has one method, close(). All readers, writers, and streams in java.io qualify, because Closeable extends AutoCloseable. The two differ slightly: Closeable.close is declared to throw IOException, AutoCloseable.close is declared to throw Exception, and an implementing class may narrow that or throw nothing.

You can make your own class a resource by implementing the interface, as the first example below does. This is the interface idea from BEG-024 at work: any class that keeps the contract can be used with the statement.

Several resources

List them separated by semicolons:

try (BufferedReader in = Files.newBufferedReader(from);
     BufferedWriter out = Files.newBufferedWriter(to)) {
    // use in and out
}

They are closed in reverse order of declaration: out first, then in. This is the sensible order, because a later resource may depend on an earlier one, as a stack of plates is cleared from the top.

catch and finally still work

You can add catch and finally blocks to a try-with-resources. The Oracle tutorial states that they run after the resources have been closed. So a catch sees a world where the files are already closed, which is exactly what you want:

1. Resources are opened, in order.
2. The block runs.
3. Resources are closed, in reverse order.
4. If something was thrown, the matching catch runs.
5. Any finally runs.

Example 1 shows this sequence with real output.

Suppressed exceptions

What if the block throws and close() throws too? With the manual version, the close exception replaced the original. With try-with-resources, the block's exception is the one that propagates, and the exception from close() is attached to it as a suppressed exception. The Throwable documentation says suppressed exceptions are typically generated by this very statement, and getSuppressed() returns them. Nothing is silently lost, and the primary failure stays on top. Example 3 demonstrates it.

When to use it

Use it for anything that implements AutoCloseable and that you open yourself: files, streams, network sockets, database connections, scanners over a file. One caution: do not wrap System.in in a try-with-resources to read the keyboard, because closing it closes the standard input for the rest of the program. Create that Scanner once at the top and leave it open.