designing with exceptions

the picture

a good error report is a chain of "because": checkout failed for order 42, because finding order 42 failed, because the database refused the connection. each link is written by someone who knows their level of the story. the web layer knows about checkouts, the repository knows about queries, the driver knows about sockets.

in java each link is an exception object, and "because" is a reference: getCause().

translate at the boundary

the rule: catch an exception where it stops making sense, and rethrow one that does make sense one level up. the repository is the last place where "SQL" is a meaningful word, so that's where SQLException turns into a DataAccessException. the service turns that into a CheckoutException. nobody above the repository imports java.sql.

and always pass the original as the cause. every standard exception has a (String message, Throwable cause) constructor for exactly this, and printStackTrace prints the chain as Caused by: sections (you saw one in exceptions).

writing your own

most of the time a standard exception is right (IllegalArgumentException, IllegalStateException, UnsupportedOperationException...). write your own when callers need to catch it specifically, or when it has to carry data a caller will use.

import java.sql.SQLException;
 
class CheckoutException extends RuntimeException {
    private final long orderId;                               // context, as a real field
 
    CheckoutException(long orderId, Throwable cause) {
        super("checkout failed for order " + orderId, cause); // message AND cause
        this.orderId = orderId;
    }
 
    long orderId() {
        return orderId;
    }
}
 
void checkout(long id) {
    try {
        throw new SQLException("Connection refused");        // pretend this came from JDBC
    } catch (SQLException e) {
        throw new CheckoutException(id, e);                   // translate, keep the cause
    }
}
 
void main() {
    try {
        checkout(42);
    } catch (CheckoutException e) {
        IO.println(e.getMessage() + ", id field = " + e.orderId());
        Throwable root = e;
        while (root.getCause() != null) root = root.getCause();
        IO.println("root cause: " + root);
    }
}

checkout failed for order 42, id field = 42
root cause: java.sql.SQLException: Connection refused

the checklist:

• pick the parent on purpose. RuntimeException for broken contracts and most application errors, Exception only if callers can genuinely recover (the three questions in exceptions).
• put the values in the message. "checkout failed for order 42" beats "checkout failed". include the inputs that caused it (but never passwords or tokens: messages end up in logs).
• keep the cause. offer a (…, Throwable cause) constructor and use it.
• expose context as fields, so callers don't have to parse your message.
• name it for the problem, ending in Exception: OrderNotFoundException, not OrderException2.
• javac -Xlint will mention a missing serialVersionUID (Throwable is Serializable). add one if your exceptions ever cross a JVM boundary, ignore it otherwise.

exceptions are for exceptional things

exceptions are cheap when nothing's thrown: a try block costs nothing until something goes wrong (it's just a row in the exception table). the expensive part is creating one, because the constructor calls fillInStackTrace(), which walks every frame on the stack. turning that into StackTraceElement objects (when you call getStackTrace() or print it) costs even more.

the honest takeaway: 235 ns is nothing for an error path, and a lot for a normal path. a parser that throws on every bad line of a big file, or a loop that ends by catching ArrayIndexOutOfBoundsException, is 100× slower than it needs to be, and hides real bugs behind a catch.

boolean isNumber(String s) {
    try {
        Integer.parseInt(s);
        return true;
    } catch (NumberFormatException e) {
        return false;   // the "normal" answer costs a stack walk
    }
}

boolean isNumber(String s) {
    return !s.isEmpty() && s.chars().allMatch(Character::isDigit);
}

leave things the way you found them

a method that throws should, ideally, leave its object exactly as it was before the call. that's called failure atomicity. the easy ways to get it: validate arguments before changing anything, compute the new state in locals and assign it at the end, or work on a copy. ArrayList.add checks capacity before it writes; a withdraw that subtracts first and checks the balance second leaves a negative balance behind when it throws.