Checked, Unchecked, and Exceptions of Your Own

The whole hierarchy is four levels, and one of them decides everything.

Throwable
├── Error                     unchecked. Not yours to catch.
└── Exception                 CHECKED. The compiler forces a catch or a throws.
    └── RuntimeException      UNCHECKED. The compiler says nothing.

RuntimeException extends Exception, and that single inheritance is the entire rule:

Exception.class.isAssignableFrom(RuntimeException.class)   // true
Exception.class.isAssignableFrom(Error.class)              // false

So: extends RuntimeException, unchecked. Extends Exception but not RuntimeException, checked. Nothing else is involved.

throw and throws are unrelated, and one letter apart:

void readConfig() throws IOException {        // throws: a warning in the signature
    if (path == null) {
        throw new IllegalStateException("no path");   // throw: it happens here, now
    }
}

throw is a statement that takes an object. throws is part of the signature and takes types. A method can declare throws and never throw, and it can throw unchecked exceptions with no throws anywhere.

Your own exception is a class that extends one of them.

public class PaymentDeclinedException extends RuntimeException {
    private final String declineCode;

    public PaymentDeclinedException(String message, String declineCode, Throwable cause) {
        super(message, cause);
        this.declineCode = declineCode;
    }

    public String declineCode() { return declineCode; }
}

Three things earn their place here.

A distinct type, so callers can catch this and not other failures. A field, so the decline code arrives as data instead of buried in a sentence. A cause, so the original failure is not lost.

Passing the cause is the part people skip:

try {
    int port = Integer.parseInt(raw);
} catch (NumberFormatException e) {
    throw new ConfigException("bad value for port: " + raw, e);   // <- the e
}

Now the trace shows your message, then Caused by: and the original underneath. Leave e out and the original trace is gone, and yours starts at the catch block rather than the failure.

Catching several the same way:

try {
    process(input);
} catch (NumberFormatException | NullPointerException e) {
    log.warn("bad input: {}", e.getMessage());
}

One block, two types, no duplication. The catch order still matters when types are related: a parent before a child will not compile, because the child could never be reached.

Answer from memory before opening the explanation. Then compare your rule with the answer and revisit the example if they differ.

1. `Files.readString(path)` will not compile without a `try`. `Integer.parseInt("abc")` compiles fine. Both can fail. Why the difference?

   Show the answer

   One is checked and the other is not, and the dividing line is a single class.

   Anything extending RuntimeException is unchecked. The compiler says nothing about it. NumberFormatException, NullPointerException and IllegalArgumentException all live there.

   Anything extending Exception but not RuntimeException is checked. The compiler forces every caller to either catch it or declare it. IOException is the one you will meet most.

   The intended split was: checked means a caller could reasonably recover, unchecked means a bug. The split does not hold in practice, which is the argument in this section.

2. What is the difference between `throw` and `throws`?

   Show the answer

   Different words doing unrelated jobs, and the missing letter is the only clue.

   throw is a statement. It happens, right now, on that line: throw new IllegalArgumentException("negative").

   throws is part of a signature. It is a warning to callers that this method might throw something, and it takes types rather than an object: void read() throws IOException.

   One does the throwing. The other declares that throwing is possible. A method can have throws and never throw, and it can throw an unchecked exception without any throws at all.

3. You catch a `NumberFormatException` and throw your own `ConfigException`. What must you pass along, and what happens if you do not?

   Show the answer

   The original exception, as the cause: throw new ConfigException("bad value for port", e).

   Do that and the stack trace shows your exception, then Caused by: and the whole original trace underneath. The reader gets your context and the line that actually failed.

   Leave it out and the original trace is gone. Your exception's trace starts at your catch block, so it points at the place you noticed the problem rather than the place it happened. On a deep stack that can be a completely different file.

   Every exception has a constructor taking a cause. Passing it costs one word and it is the difference between a report and a dead end.

Write each solution in VS Code, predict its result, and then run the checks. Reading an example does not replace implementing it.

4 exercises100 pointsabout 105 minutes

class Divide {
    static boolean isUnchecked(Class<?> type)
    static boolean isChecked(Class<?> type)
    static boolean isNeither(Class<?> type)
    static String classify(Class<?> type)
    static String catchIt(String path)
    static String declareIt(String path) throws IOException
    static String callerOfDeclared(String path)
}

import java.io.*;
import java.sql.SQLException;

public class Divide {

    // Sort these before writing any code:
    //   IOException  NumberFormatException  SQLException  IllegalArgumentException
    //   FileNotFoundException  NullPointerException  InterruptedException
    //   ClassNotFoundException  ArithmeticException  OutOfMemoryError
    //
    // Then answer by ASKING THE TYPE SYSTEM. The checks pass classes not listed here.

    static boolean isUnchecked(Class<?> type) { return false; }  // TODO
    static boolean isChecked(Class<?> type)   { return false; }  // TODO
    static boolean isNeither(Class<?> type)   { return false; }  // TODO
    static String classify(Class<?> type)     { return ""; }     // TODO

    // The two ways past a checked exception.
    static String catchIt(String path) { return ""; }  // TODO: handle it here
    static String declareIt(String path) throws IOException { return ""; }  // TODO: pass it up
    static String callerOfDeclared(String path) { return ""; }  // TODO: handle it one level up

    public static void main(String[] args) {
        // TODO: classify all ten and check against your sorting
    }
}

class Causes {
    static int readPortLosingCause(String raw)
    static int readPortKeepingCause(String raw)
    static String causeTypeOf(Runnable work)
    static String deepestFrameOf(Runnable work)
    static String parseNullType()
}

public class Causes {

    static class ConfigException extends RuntimeException {
        ConfigException(String message) { super(message); }
        ConfigException(String message, Throwable cause) { super(message, cause); }
    }

    // The same job twice. One throws away the original, one keeps it.
    static int readPortLosingCause(String raw)  { return 0; }  // TODO
    static int readPortKeepingCause(String raw) { return 0; }  // TODO

    // "none" when there is no cause, otherwise the cause's simple name.
    static String causeTypeOf(Runnable work) { return ""; }  // TODO

    // Follow getCause to the bottom, and name where THAT trace starts.
    static String deepestFrameOf(Runnable work) { return ""; }  // TODO

    // Predict this one before running it.
    static String parseNullType() { return ""; }  // TODO: Integer.parseInt(null)

    public static void main(String[] args) {
        // TODO: throw both versions and read the FULL trace of each
    }
}

class Payment {
    static void charge(String card, int amount)
    static String attempt(String card, int amount)
    static String catchOnlyArgumentProblems(String card, int amount)
    static boolean isUnchecked()
}

public class Payment {

    // TODO: PaymentDeclinedException. It needs:
    //   a distinct type, so callers can catch this and not other failures
    //   a decline code as a FINAL FIELD, not buried in the message
    //   a constructor taking a cause

    static void charge(String card, int amount) {
        // TODO: amount <= 0            -> IllegalArgumentException
        //       card starts with 4000  -> declined, code insufficient_funds
        //       card starts with 4001  -> declined, code expired_card
    }

    // Catch the decline and branch on the CODE, not on the message text.
    static String attempt(String card, int amount) { return ""; }  // TODO

    // Catch ONLY argument problems. A decline must pass straight through.
    static String catchOnlyArgumentProblems(String card, int amount) { return ""; }  // TODO

    static boolean isUnchecked() { return false; }  // TODO

    public static void main(String[] args) {
        // TODO: try all three kinds of card
    }
}

class Clash {
    static boolean consumerCanDeclareChecked()
    static String mightFail(String name) throws Exception
    static List<String> readAllWrapping(List<String> names)
    static List<String> readAllWithHelper(List<String> names)
    static String causeOf(Runnable work)
    static long timeThrows(int n, boolean withTrace)
    static int traceLengthOf(boolean withTrace)
}

import java.util.*;
import java.util.function.*;

public class Clash {

    // Try: names.forEach(n -> mightFail(n));  Read the error.
    // Then look at Consumer.accept and work out why it cannot be widened.
    static boolean consumerCanDeclareChecked() { return true; }  // TODO

    static String mightFail(String name) throws Exception {
        if (name.startsWith("bad")) throw new Exception("cannot read " + name);
        return name.toUpperCase();
    }

    // TODO: an unchecked exception to wrap in, keeping the cause
    static class WrappedException extends RuntimeException {
        WrappedException(String message, Throwable cause) { super(message, cause); }
    }

    // Use forEach. Catch inside the lambda and wrap.
    static List<String> readAllWrapping(List<String> names) { return List.of(); }  // TODO

    // TODO: your own functional interface that DOES declare a checked exception,
    //       plus a helper that adapts one into an ordinary Function

    static List<String> readAllWithHelper(List<String> names) { return List.of(); }  // TODO

    static String causeOf(Runnable work) { return ""; }  // TODO

    // TODO: a FastException using super(m, null, false, false), so it has no trace

    static long timeThrows(int n, boolean withTrace) { return 0; }  // TODO
    static int traceLengthOf(boolean withTrace) { return -1; }  // TODO

    public static void main(String[] args) {
        // TODO: 200_000 throws each way, warmed up first
    }
}