Exception Handling in Java

// CHECKED EXCEPTIONS: Must be declared or handled
// Philosophy: "Recoverable errors the caller should know about"

public String readFile(String path) throws IOException {
    // IOException is checked - declared in signature
    return Files.readString(Path.of(path));
}

// Caller MUST handle or propagate
public void process() {
    // Option 1: Handle it
    try {
        String content = readFile("data.txt");
    } catch (IOException e) {
        log.error("Failed to read file", e);
        // Recover, retry, or throw different exception
    }

    // Option 2: Propagate it
    // public void process() throws IOException { ... }
}

// Common checked exceptions:
// - IOException (file/network operations)
// - SQLException (database operations)
// - ParseException (parsing dates, etc.)
// - InterruptedException (threading)

// Checked exception - caller must handle
// Use when caller can reasonably recover

public class InsufficientFundsException extends Exception {
    private final BigDecimal requested;
    private final BigDecimal available;

    public InsufficientFundsException(BigDecimal requested, BigDecimal available) {
        super(String.format(
            "Requested %s but only %s available",
            requested, available
        ));
        this.requested = requested;
        this.available = available;
    }

    public BigDecimal getRequested() { return requested; }
    public BigDecimal getAvailable() { return available; }
}

// Usage
public void withdraw(BigDecimal amount) throws InsufficientFundsException {
    if (amount.compareTo(balance) > 0) {
        throw new InsufficientFundsException(amount, balance);
    }
    balance = balance.subtract(amount);
}

// Don't leak implementation details through exceptions
// Translate low-level exceptions to domain exceptions

public class UserRepository {
    public User findById(String id) {
        try {
            return jdbc.queryForObject(
                "SELECT * FROM users WHERE id = ?",
                userRowMapper,
                id
            );
        } catch (EmptyResultDataAccessException e) {
            // Translate to domain exception
            throw new UserNotFoundException(id);
        } catch (DataAccessException e) {
            // Wrap with cause preserved
            throw new RepositoryException("Failed to find user", e);
        }
    }
}

// Caller doesn't need to know about JDBC, SQL, or data access details
// They deal with UserNotFoundException and RepositoryException

// Always preserve the root cause!

public Config loadConfig() {
    try {
        String json = Files.readString(Path.of("config.json"));
        return objectMapper.readValue(json, Config.class);
    } catch (IOException e) {
        // BAD: loses original exception
        // throw new ConfigException("Failed to load config");

        // GOOD: preserves cause chain
        throw new ConfigException("Failed to load config", e);
    } catch (JsonProcessingException e) {
        throw new ConfigException("Invalid config format", e);
    }
}

// When debugging, you see the full stack trace:
// ConfigException: Failed to load config
//   at ConfigLoader.loadConfig(ConfigLoader.java:25)
// Caused by: java.io.FileNotFoundException: config.json
//   at java.io.FileInputStream.open0(Native Method)
//   ...

// Validate inputs immediately - don't wait until deep in the call stack

public class UserService {

    public User createUser(String name, String email) {
        // Fail fast with clear messages
        Objects.requireNonNull(name, "name cannot be null");
        Objects.requireNonNull(email, "email cannot be null");

        if (name.isBlank()) {
            throw new IllegalArgumentException("name cannot be blank");
        }
        if (!EMAIL_PATTERN.matcher(email).matches()) {
            throw new IllegalArgumentException("invalid email format");
        }

        // Now we KNOW inputs are valid - no need to check again
        return repository.save(new User(name, email));
    }
}

// Using Guava Preconditions (cleaner)
import static com.google.common.base.Preconditions.*;

public User createUser(String name, String email) {
    checkNotNull(name, "name cannot be null");
    checkArgument(!name.isBlank(), "name cannot be blank");
    checkArgument(isValidEmail(email), "invalid email: %s", email);

    return repository.save(new User(name, email));
}

// Use Optional when absence is expected, not exceptional

public Optional<User> findByEmail(String email) {
    return repository.findByEmail(email);  // May be empty
}

// Caller handles presence/absence explicitly
User user = findByEmail("alice@example.com")
    .orElseThrow(() -> new UserNotFoundException(email));

// Or with default
User user = findByEmail(email)
    .orElse(createGuestUser());

// Or with lazy default
User user = findByEmail(email)
    .orElseGet(() -> createGuestUser());

// Chaining
String city = findByEmail(email)
    .map(User::getAddress)
    .map(Address::getCity)
    .orElse("Unknown");