throw, throws and signalling failure honestly

Understanding throw, throws and signalling failure honestly

The two keywords look alike and do unrelated jobs. throw is an executable statement that takes a single exception object, which is why it almost always reads throw new SomethingException(...); the instant it runs, the method stops producing a value and the JVM starts searching the call stack for a handler. throws is not code at all: it is a clause on the signature that tells the compiler which checked exception types are permitted to leave the method. Because a throw ends the method, any statement after it in the same block is unreachable and javac rejects it, and for the same reason a method may end with a throw where a return would otherwise be required.

Treat the throws clause as the part of the contract a caller reads before writing a single line against your method. It is enforced only for checked types; listing RuntimeException subclasses there changes nothing the compiler does and works purely as documentation. The clause is a ceiling, not a prediction: a method declared throws TimeoutException might never throw one, yet every caller must still catch it or re-declare it, so an over-broad clause imposes real work on people who will never see that failure. throws Exception is the extreme case, satisfying javac while telling callers only that something, somewhere, may go wrong.

Signalling honestly means the type and the timing of the throw match what the caller should do about it. Check arguments first and throw IllegalArgumentException, or IllegalStateException for a bad object state, with the rejected value in the message, so the failure surfaces before the method has done half its work or touched shared state. When the failure is an expected fact about the outside world such as a timeout, a missing file or a declined payment, choose a specific checked type and name it, which forces the caller to have a plan. What ruins all of this is encoding failure as -1, null, false or an empty list, because those values flow onward silently and the bug then appears far away from its cause.

The signature and the throw site are one design decision: the throw picks the type, the clause publishes it, and a caller who only reads the signature should already know what to plan for.

import java.util.concurrent.TimeoutException;

public class Main {

    // The throws clause is a promise to callers: plan for a timeout.
    // IllegalArgumentException is a caller bug, so it stays out of the clause.
    static String fetch(String host, int timeoutMs) throws TimeoutException {
        if (timeoutMs <= 0) {
            throw new IllegalArgumentException("timeoutMs must be > 0, got " + timeoutMs);
        }
        if (host.equals("slow.example")) {
            throw new TimeoutException("no answer from " + host + " in " + timeoutMs + "ms");
        }
        return "200 OK from " + host;
    }

    public static void main(String[] args) throws TimeoutException {
        try {
            System.out.println(fetch("fast.example", 500));
            System.out.println(fetch("slow.example", 500));
            System.out.println("this line is skipped: the throw left fetch and the try block");
        } catch (TimeoutException e) {
            System.out.println("handled: " + e.getMessage());
        }

        try {
            fetch("fast.example", 0);
        } catch (IllegalArgumentException e) {
            System.out.println("refused before any work: " + e.getMessage());
        }

        System.out.println(fetch("fast.example", 500));
    }
}

Worked examples

import java.util.concurrent.TimeoutException;

public class Main {

    // Vague: the signature says anything may fail, so callers learn nothing.
    static String vagueFetch(String host) throws Exception {
        throw new TimeoutException(host);
    }

    // Precise: the one recoverable failure mode is named.
    static String preciseFetch(String host) throws TimeoutException {
        throw new TimeoutException(host);
    }

    public static void main(String[] args) {
        try {
            vagueFetch("a.example");
        } catch (Exception e) {
            System.out.println("vague: signature said Exception, runtime brought "
                    + e.getClass().getSimpleName());
        }

        try {
            preciseFetch("b.example");
        } catch (TimeoutException e) {
            System.out.println("precise: timeout talking to " + e.getMessage() + ", retrying");
        }
    }
}

import java.util.concurrent.TimeoutException;

public class Main {

    static class Source {
        String read() throws TimeoutException {
            throw new TimeoutException("network stalled");
        }
    }

    static class Cache extends Source {
        @Override
        String read() {                      // narrower contract: it cannot time out
            return "cached value";
        }
    }

    public static void main(String[] args) {
        Cache cache = new Cache();
        System.out.println(cache.read());    // no handling required at all

        Source source = cache;               // same object, wider declared contract
        try {
            System.out.println(source.read());
        } catch (TimeoutException e) {
            System.out.println("would have handled: " + e.getMessage());
        }
    }
}

Important notes

Common mistakes

Try it yourself