Java Exceptions — Complete Notes

int result = divide(10, 0);   // returns -1 to mean "error"
System.out.println(result);   // prints -1 and carries on happily
                              // The bug travels silently through your whole program.

int divide(int a, int b) {
    if (b == 0) throw new ArithmeticException("cannot divide by zero");
    return a / b;
}

int result = divide(10, 0);   // this line never completes
System.out.println(result);   // never runs — control has already left

void main()  { a(); }              // 3. no catch here either -> thread dies, trace printed
void a()     { b(); }              // 2. no catch here -> keep climbing
void b()     { throw new IllegalStateException("boom"); }  // 1. thrown here

// Output:
// Exception in thread "main" java.lang.IllegalStateException: boom
//     at Demo.b(Demo.java:8)
//     at Demo.a(Demo.java:6)
//     at Demo.main(Demo.java:4)

              Object
                |
            Throwable                 <- the root of everything throwable
             /      \
          Error    Exception
            |        /      \
            |       |    RuntimeException
            |       |          |
            |       |    - NullPointerException
            |       |    - IllegalArgumentException
            |       |    - IllegalStateException
            |       |    - IndexOutOfBoundsException
            |       |    - ArithmeticException
            |       |    - ClassCastException
            |       |
            |    (checked exceptions)
            |     - IOException
            |     - FileNotFoundException
            |     - SQLException
            |     - InterruptedException
            |
        (unrecoverable JVM problems)
         - OutOfMemoryError
         - StackOverflowError
         - NoClassDefFoundError

// IOException is checked, so ONE of these two is mandatory:

// Option A — handle it here
void readA() {
    try {
        Files.readString(Path.of("a.txt"));
    } catch (IOException e) {
        System.out.println("could not read: " + e.getMessage());
    }
}

// Option B — declare it and make it the caller's problem
void readB() throws IOException {
    Files.readString(Path.of("a.txt"));
}

// Option C — do neither
void readC() {
    Files.readString(Path.of("a.txt"));   // COMPILE ERROR:
}                                          // unreported exception IOException; must be caught or declared

void parse(String s) {
    int n = Integer.parseInt(s);   // throws NumberFormatException (unchecked)
}                                  // Compiles fine. No try, no throws. Blows up at runtime if s is "abc".

try {
    riskyThing();
} catch (IOException e) {
    // nothing here. "I'll deal with it later."
}
// The failure is now invisible. No log, no trace, no clue.
// Debugging this at 3am is genuinely miserable.

String load()   throws IOException, SQLException, ParseException { ... }
String service() throws IOException, SQLException, ParseException { return load(); }
String handler() throws IOException, SQLException, ParseException { return service(); }
// Every layer is forced to name low-level failures it has no interest in.

try {
    // code that might throw
} catch (FileNotFoundException e) {
    // runs ONLY for this type (or a subclass of it)
} catch (IOException e) {
    // runs for other IOExceptions
} finally {
    // ALWAYS runs — exception or not, return or not
}

try {
    read();
} catch (IOException e) {           // broad
} catch (FileNotFoundException e) { // COMPILE ERROR:
}                                   // exception FileNotFoundException has already been caught

// Correct: subclass first, superclass second.
try {
    read();
} catch (FileNotFoundException e) { // specific
} catch (IOException e) {           // general fallback
}

try {
    process();
} catch (IOException | SQLException e) {     // handle both the same way
    log.error("processing failed", e);
    throw new ProcessingException(e);
}

int f() {
    try {
        return 1;        // value 1 is computed and held...
    } finally {
        System.out.println("cleanup");   // ...but this runs BEFORE the method actually returns
    }
}
// prints "cleanup", then returns 1

int bad() {
    try {
        throw new RuntimeException("the real problem");
    } finally {
        return 42;      // the exception is thrown away. Caller sees 42 and thinks all is well.
    }
}
// bad() returns 42. The RuntimeException vanishes without trace.

// 1. The JVM exits
try { System.exit(0); } finally { System.out.println("never printed"); }

// 2. The thread is killed, or the JVM crashes / is SIGKILLed
// 3. An infinite loop or deadlock inside try means you never leave it

BufferedReader br = null;
try {
    br = new BufferedReader(new FileReader("a.txt"));
    System.out.println(br.readLine());
} catch (IOException e) {
    log.error("read failed", e);
} finally {
    if (br != null) {
        try { br.close(); }          // close() itself throws IOException, so another try...
        catch (IOException ignored) {}   // ...and now you're swallowing again
    }
}

try (BufferedReader br = new BufferedReader(new FileReader("a.txt"))) {
    System.out.println(br.readLine());
} catch (IOException e) {
    log.error("read failed", e);
}
// br.close() is called automatically, guaranteed, even if readLine() throws.

class Connection implements AutoCloseable {
    Connection() { System.out.println("open"); }
    void use()   { System.out.println("using"); }
    @Override public void close() { System.out.println("closed"); }  // narrowed: throws nothing
}

try (Connection c = new Connection()) {
    c.use();
}
// open
// using
// closed

try (Connection c = new Connection();
     Statement s = c.createStatement();
     ResultSet r = s.executeQuery(sql)) {
    // use r
}
// close order: r, then s, then c
// Note: the semicolon after the LAST resource is optional.

class Bad implements AutoCloseable {
    void use()  { throw new RuntimeException("primary — the real bug"); }
    public void close() { throw new RuntimeException("secondary — from close()"); }
}

try (Bad b = new Bad()) {
    b.use();
} catch (Exception e) {
    System.out.println(e.getMessage());                    // primary — the real bug
    System.out.println(e.getSuppressed()[0].getMessage()); // secondary — from close()
}

Bad b = new Bad();
try {
    b.use();               // throws "primary" ...
} finally {
    b.close();             // ... then this throws "secondary", REPLACING it entirely.
}
// Caller sees only "secondary". The actual bug is gone forever.

void withdraw(int amount) throws InsufficientFundsException {   // declaration
    if (amount > balance) {
        throw new InsufficientFundsException("need " + amount + ", have " + balance);  // action
    }
    balance -= amount;
}

class Parent {
    void go() throws IOException { }
}

class Child extends Parent {
    // ALLOWED — same exception
    void go() throws IOException { }
}
class Child2 extends Parent {
    // ALLOWED — narrower (FileNotFoundException extends IOException)
    void go() throws FileNotFoundException { }
}
class Child3 extends Parent {
    // ALLOWED — fewer: declaring nothing at all is always fine
    void go() { }
}
class Child4 extends Parent {
    // COMPILE ERROR — broader. Exception is a supertype of IOException.
    void go() throws Exception { }
}
class Child5 extends Parent {
    // COMPILE ERROR — brand new checked exception the parent never mentioned
    void go() throws SQLException { }
}
class Child6 extends Parent {
    // ALLOWED — unchecked exceptions are never part of the contract, declare freely
    void go() throws IllegalStateException { }
}

// Unchecked: extend RuntimeException (the usual default)
public class InsufficientFundsException extends RuntimeException {

    private final BigDecimal shortfall;   // carry USEFUL data, not just a string

    public InsufficientFundsException(String message) {
        super(message);
        this.shortfall = null;
    }

    public InsufficientFundsException(String message, Throwable cause) {
        super(message, cause);            // NEVER drop the cause
        this.shortfall = null;
    }

    public InsufficientFundsException(String message, BigDecimal shortfall) {
        super(message);
        this.shortfall = shortfall;
    }

    public BigDecimal getShortfall() { return shortfall; }
}

// Checked: extend Exception instead — everything else is identical
public class ConfigurationException extends Exception {
    public ConfigurationException(String message, Throwable cause) { super(message, cause); }
}

void setAge(int age) {
    if (age < 0) throw new IllegalArgumentException("age must be >= 0, got: " + age);
    this.age = age;
}

void send() {
    if (!connected) throw new IllegalStateException("call connect() before send()");
    ...
}

Order(Customer c) {
    // throws NPE with a clear message instead of a mystery NPE three calls later
    this.customer = Objects.requireNonNull(c, "customer must not be null");
}

String read(Path p) throws IOException {
    return Files.readString(p);   // nothing useful to add here — let the caller deal with it
}

public User findUser(long id) {
    try {
        return jdbc.query("SELECT ...", id);
    } catch (SQLException e) {
        // Translate to MY layer's vocabulary — but keep `e` as the cause!
        throw new UserLookupException("could not load user " + id, e);
    }
}

UserLookupException: could not load user 7
    at UserService.findUser(UserService.java:22)
    at UserController.get(UserController.java:14)
Caused by: java.sql.SQLException: connection refused        <- the actual reason
    at org.postgresql.Driver.connect(Driver.java:198)
    ... 12 more

Exception in thread "main" java.lang.NullPointerException: Cannot invoke
    "String.length()" because "name" is null                 <- (1) WHAT + why (helpful NPE, Java 14+)
    at com.app.User.nameLength(User.java:42)                 <- (2) WHERE it was thrown — start here
    at com.app.UserService.process(UserService.java:18)      <- (3) who called it
    at com.app.Main.main(Main.java:7)                        <- (4) the entry point
Caused by: java.sql.SQLException: connection refused         <- (5) the ROOT cause — often the real story
    at org.postgresql.Driver.connect(Driver.java:198)
    ... 12 more                                              <- (6) frames identical to the trace above