Defining Custom Exception Classes

## Background: the exception hierarchy In Java, everything you can `throw` descends from the class **`Throwable`**. `Throwable` has two direct subclasses: - **`Error`** — serious problems the application normally cannot recover from (e.g. `OutOfMemoryError`, `StackOverflowError`). You do not create or catch these in normal code. - **`Exception`** — conditions an application might want to handle. Under `Exception` there is a special subclass, **`RuntimeException`**. This split defines two categories: - **Checked exceptions**: any subclass of `Exception` that is *not* a subclass of `RuntimeException`. - **Unchecked exceptions**: `RuntimeException` and its subclasses (plus `Error`). ## What "checked" actually means "Checked" refers to a **compile-time rule** enforced by the Java compiler, called the *handle-or-declare* requirement. If a method body can throw a checked exception, the method must either: 1. **catch** it in a `try`/`catch` block, or 2. **declare** it in the method signature with a `throws` clause, e.g. `void load() throws IOException`. If you do neither, the code does not compile. Unchecked exceptions have **no** such requirement — you can throw them anywhere and callers are never forced by the compiler to do anything. ## So which base class do you extend? When you write `class MyException extends Exception`, your exception is **checked**. When you write `class MyException extends RuntimeException`, it is **unchecked**. That single choice of superclass is what determines the compile-time contract. ### The decision guideline The classic guidance (from *Effective Java* and the Java tutorials) is: > Use **checked** exceptions for **recoverable** conditions — situations where a reasonable caller can do something useful in response (retry, fall back, ask the user). The checked contract *forces* the caller to acknowledge the possibility. > > Use **unchecked** (`RuntimeException`) exceptions for **programming errors** and precondition violations — bugs like passing `null` where it is forbidden, or calling a method in the wrong state. The caller usually cannot recover from a bug; forcing try/catch everywhere only adds clutter. Examples from the JDK reinforce this: `IOException` (a file might genuinely be missing — recoverable) is checked; `IllegalArgumentException` and `IllegalStateException` and `NullPointerException` (bugs) are unchecked. ### Practical trade-offs - **Checked pros:** the compiler guarantees the caller is aware of and addresses the failure mode; the failure is part of the documented API. - **Checked cons:** they propagate up through every signature, polluting `throws` clauses, and they leak implementation details across abstraction layers (a high-level method shouldn't have to declare a low-level `SQLException`). They also interact badly with lambdas/streams, whose functional interfaces don't declare checked exceptions. - **Unchecked pros:** clean signatures, easy composition, work with lambdas. - **Unchecked cons:** nothing reminds the caller the exception exists, so it can slip through unhandled. Because of the cons of checked exceptions, many modern frameworks (notably **Spring**, which wraps `SQLException` into the unchecked `DataAccessException`) and many style guides default to **unchecked** custom exceptions, reserving checked ones for cases where forcing handling genuinely adds value. ## Rules of thumb to remember - Extend `Exception` → checked → "caller must deal with it" → recoverable conditions. - Extend `RuntimeException` → unchecked → "this is a bug or unrecoverable" → no compiler ceremony. - Never extend `Throwable` or `Error` directly for your own application exceptions. - Be consistent within a codebase/module; mixing arbitrarily confuses callers.