Java Try-with-resources

Closing without a second try

Before Java 7, a reader was closed in finally, and close itself throws IOException, so the cleanup needed another try. If the read had already thrown, a throw from close replaced it. The caller's catch saw the close, and the read error was gone.

The header form declares the resource, uses it in the body, and closes it when the statement ends, whether the body finished, threw, or returned. BufferedReader implements AutoCloseable through Closeable. The close exception from a reader is still IOException, so this method still has to catch it or declare it. Closing is not handling. The catch is still yours if you want a sentence for a missing file.

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

static String firstLine(String path) throws IOException {
    try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
        return reader.readLine();
    }
}

Several resources go in one header, separated by semicolons. Declare the inner resource first and the wrapper after it. Close order is the reverse, so the wrapper closes while the thing it uses is still open.

try (
    FileReader file = new FileReader("input.txt");
    BufferedReader reader = new BufferedReader(file)
) {
    return reader.readLine();
}

The failure that must stay visible

These doors throw on purpose, so the order is visible without a filesystem. enter throws. Then the resources close, inner first, then outer, and each close throws as well.

class Door implements AutoCloseable {
    private final String name;

    Door(String name) {
        this.name = name;
    }

    void enter() {
        throw new IllegalStateException("could not enter");
    }

    @Override
    public void close() {
        throw new IllegalStateException(name + " stuck");
    }
}

static void visit() {
    try (Door outer = new Door("outer"); Door inner = new Door("inner")) {
        inner.enter();
    } catch (IllegalStateException e) {
        System.out.println(e.getMessage());
        for (Throwable suppressed : e.getSuppressed()) {
            System.out.println("suppressed: " + suppressed.getMessage());
        }
    }
}

visit prints could not enter, then suppressed: inner stuck, then suppressed: outer stuck. The primary exception is the one from the body. Closing still happens, both of them, and each failure is added with addSuppressed on that primary object. printStackTrace shows the same extras under a Suppressed: heading. Your catch runs after the closes, so getSuppressed is already populated when you see the exception. A finally you write on this statement runs after that catch, by the ordinary finally rule.

If enter had succeeded and only the closes threw, there would be no body exception to keep. The first close failure, from inner, would propagate, and outer's close failure would be suppressed on it. If the body succeeds and every close succeeds, nothing is thrown. The suppressed list is how a second failure is preserved. It is not a second channel that always fires.

A constructor that fails halfway

Initialization is left to right. If inner's constructor throws, outer has already been constructed, and it is closed. inner is not closed, because no object was bound. Should outer.close throw too, that exception is suppressed on the constructor failure, which remains the one that propagates.

class Door implements AutoCloseable {
    final String name;

    Door(String name) {
        if (name.equals("inner")) {
            throw new IllegalStateException("inner failed to open");
        }
        this.name = name;
    }

    @Override
    public void close() {
        throw new IllegalStateException(name + " stuck");
    }
}

try (Door outer = new Door("outer"); Door inner = new Door("inner")) {
    outer.toString();
}

The catch sees inner failed to open, with outer stuck suppressed. The body never ran. This is the same attachment rule as a body failure: something already went wrong, later cleanup went wrong too, and the first wrong stays primary.

A variable you already have

Java 9 allows an effectively final variable in the header. The constructor can sit outside, so a failure to open is a different statement from a failure while reading. The close still happens at the end of the try.

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

static String firstLine(String path) throws IOException {
    BufferedReader reader = new BufferedReader(new FileReader(path));
    try (reader) {
        return reader.readLine();
    }
}

reader is never assigned again, so it may appear alone in the header. After the statement, the variable is still in scope and the reader is closed. Returning reader from inside the try would return it only after close runs, by the same rule that delays a return until finally has finished. The caller would hold a closed reader. If the caller must own the lifetime, do not put the object in the header. Hand it back and let the caller write the try-with-resources.

close on your own types should tolerate a second call. A session that shuts down on the first close can return on the second. Throwing the second time punishes a caller who closed in a header and also closed in a defensive finally. The interesting exception is the first failure, not a complaint that cleanup happened twice.