Explain the 'recoverable condition vs programming error' rule for choosing checked vs unchecked custom exceptions, with examples of each.

## Why this rule exists Java is the rare mainstream language with two flavors of exception, and the only thing that separates them is whether the **compiler forces the caller to deal with them**. So the real question is: *for this particular failure, do I want to compel every caller to write handling code?* The 'recoverable vs programming error' rule is the heuristic that answers it. ## Defining the two categories **Recoverable condition.** A runtime situation that is not a bug — the code did everything right but the world didn't cooperate, AND the caller has a *useful* response available. 'Useful response' means more than logging: retry, switch to a backup, ask the user for new input, return a default, queue for later. Because such a response is possible and desirable, you use a **checked** exception so the compiler guarantees the caller at least acknowledges it. *Examples worth making checked:* - A file the user supplied is malformed → prompt for another file. - A remote service times out → retry or fall back to cache. - A bank transfer hits insufficient funds → report it to the user. **Programming error.** A failure caused by misuse of the API — a violated *precondition*. The caller passed something illegal or called a method in an illegal state. The right fix is to **correct the code**, not to write recovery logic, so forcing a `catch` adds noise without value. These are **unchecked**. *Examples that should be unchecked:* - `null` passed where the contract forbids it → `NullPointerException`. - Index outside array bounds → `IndexOutOfBoundsException`. - Calling `next()` on an exhausted iterator → `IllegalStateException`. - An argument outside the legal range → `IllegalArgumentException`. ## A third bucket: unrecoverable conditions Some non-bug conditions are still impossible (or pointless) to recover from at the call site — e.g. a critical resource is permanently unavailable. Even though these aren't programming errors, forcing a `catch` no one can act on is just ceremony, so the pragmatic choice is usually **unchecked** (often wrapping the original cause). `Error` is the extreme end of this (e.g. `OutOfMemoryError`) — the app shouldn't try to handle it at all. ## The practical test Ask: *if I write `try { ... } catch (ThisException e) { ... }` at a typical call site, what goes in the catch block?* - If it would contain **real recovery** (retry, fallback, user prompt) → the condition is recoverable → **checked** is justified. - If it would just **log and rethrow**, or there's nothing sensible to do → don't force it → **unchecked**. ## Why not just make everything checked? Because checked exceptions impose costs: `throws` clauses propagate up the call chain, they leak low-level concerns into high-level APIs (a leaky abstraction), they don't fit Java's functional interfaces (lambdas/streams), and they tempt developers into swallowing exceptions with empty catch blocks — which is worse than a clear unchecked failure. So the rule isn't 'prefer checked'; it's 'make checked only the failures a caller genuinely should be forced to handle, and make everything else unchecked.' ## Why not just make everything unchecked? Because then a genuinely recoverable, important failure becomes invisible in the type system — a caller can forget it exists and ship code that crashes in production on a condition they could have handled. Checked exceptions, used sparingly, encode 'you really need to deal with this' into the contract in a way the compiler enforces. The art is reserving them for exactly those cases. ## Documentation either way Whichever you choose, document the exception in Javadoc with `@throws`, explaining the condition and the expected recovery. This is *mandatory* for unchecked exceptions (the type system won't advertise them) and good practice for checked ones.