exceptions

the picture

someone pulls the fire alarm on floor 7 (that's throw). the alarm doesn't go to whoever's nearest: it goes down the building, floor by floor, to the people who sent you up there (the callers), and the first one whose job it is to handle fires handles it (that's catch). if nobody does, everyone's evacuated: the thread dies and the alarm gets printed on stderr.

void main() {
    try {
        int[] a = new int[3];
        a[3] = 1;                                   // the JVM throws for you
    } catch (ArrayIndexOutOfBoundsException e) {    // e is just an object
        IO.println(e.getMessage());
        IO.println(e.getClass().getName());
        IO.println(e.getStackTrace()[0]);           // where it happened
    }
}

Index 3 out of bounds for length 3
java.lang.ArrayIndexOutOfBoundsException
Main.main(Main.java:4)

you can throw your own just as easily:

throw new IllegalArgumentException("qty must be > 0");

new builds the object, throw starts the trip down the stack. exactly how that trip goes, frame by frame, is the next chapter: try, catch, finally.

the family tree

Throwable holds everything an exception carries: a message, an optional cause (another throwable that led to this one), a stack trace, and a list of suppressed exceptions (for try-with-resources). the subclasses mostly just add a name. the name is the information: catch picks handlers by class.

checked vs unchecked

checked exceptions are part of a method's signature. if a method can throw one, it must say so with throws, and every caller must either catch it or declare it too. javac enforces this, not the JVM:

import java.nio.file.Files;
import java.nio.file.Path;
 
public class Config {
    static String load(Path p) {
        return Files.readString(p);
    }
}

Config.java:6: error: unreported exception IOException; must be caught or declared to be thrown
        return Files.readString(p);
                               ^

two ways out: handle it with a try/catch, or pass it on by adding throws IOException to the signature, which makes it your callers' problem. unchecked exceptions (RuntimeException, Error and their subclasses) skip all of that. you can still catch them, nobody makes you.

so which should your code throw? three questions settle almost every case:

the idea behind the split: a checked exception is part of the method's contract, a thing that can go wrong even in a perfect program, so the caller should be made to think about it. an unchecked exception means someone broke the contract: the fix is to change code, not to catch.

checked exceptions vs lambdas

here's where checked exceptions get annoying. Function.apply doesn't declare any exceptions, so a lambda passed to map can't throw a checked one, even if the enclosing method declares it:

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
 
public class Lambda {
    static List<String> loadAll(List<Path> paths) throws java.io.IOException {
        return paths.stream().map(p -> Files.readString(p)).toList();
    }
}

Lambda.java:7: error: unreported exception IOException; must be caught or declared to be thrown
        return paths.stream().map(p -> Files.readString(p)).toList();
                                                       ^

the usual fix is to wrap it in the unchecked exception the JDK made for exactly this:

paths.stream().map(p -> {
    try {
        return Files.readString(p);
    } catch (IOException e) {
        throw new UncheckedIOException(e);   // keeps the original as the cause
    }
}).toList();

or just write the for loop, which can throw anything its method declares. (this friction is a big part of why kotlin, scala and C# dropped checked exceptions altogether. java kept them, and the modern consensus is "use them sparingly".)

reading a stack trace

when nobody catches an exception, the thread prints its class, message, stack trace and causes. here's a real one: parse catches a NumberFormatException and rethrows it wrapped in an IllegalArgumentException.

record Address(String city) {}
record User(String name, Address address) {}
 
void main() {
    var u = new User("ada", null);
    IO.println(u.address().city().length());
}