Java Checked vs Unchecked Exceptions Explained — When to Use Each

public class ExceptionHierarchyDemo {

    public static void main(String[] args) {

        // --- Checked Exception Example ---
        // IOException extends Exception directly, so the compiler
        // FORCES us to handle or declare it. Removing the try-catch
        // causes a compile error: "unreported exception IOException".
        try {
            readConfigFile("/etc/app/config.properties");
        } catch (java.io.IOException ioException) {
            // We handle the realistic possibility that the file isn't there
            System.out.println("Config file problem: " + ioException.getMessage());
        }

        // --- Unchecked Exception Example ---
        // NumberFormatException extends RuntimeException, so no compile
        // error if we skip the try-catch. The compiler trusts us.
        // But at runtime, passing a bad string will blow up here.
        String rawUserInput = "42"; // pretend this came from a form field
        int parsedAge = Integer.parseInt(rawUserInput); // safe with "42"
        System.out.println("Parsed age: " + parsedAge);

        // Now intentionally cause an unchecked exception to show the output
        String corruptInput = "forty-two";
        try {
            int badParse = Integer.parseInt(corruptInput);
        } catch (NumberFormatException numberFormatException) {
            // NumberFormatException is unchecked — we only catch it
            // at the boundary where raw input enters our system
            System.out.println("Bad input caught at boundary: " + numberFormatException.getMessage());
        }

        // Demonstrate the hierarchy programmatically
        NumberFormatException nfe = new NumberFormatException("demo");
        System.out.println("Is RuntimeException? " + (nfe instanceof RuntimeException)); // true
        System.out.println("Is Exception?        " + (nfe instanceof Exception));        // true

        java.io.IOException ioe = new java.io.IOException("demo");
        System.out.println("IOException is RuntimeException? " + (ioe instanceof RuntimeException)); // false
        System.out.println("IOException is Exception?        " + (ioe instanceof Exception));        // true
    }

    // 'throws IOException' is mandatory — omitting it is a compile error
    static void readConfigFile(String filePath) throws java.io.IOException {
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(filePath));
    }
}

// ── Checked: realistic external failure the caller must plan for ──
class PaymentGatewayException extends Exception {

    private final int httpStatusCode;

    public PaymentGatewayException(String message, int httpStatusCode) {
        super(message);
        this.httpStatusCode = httpStatusCode;
    }

    // Always include a cause constructor — wrapping preserves stack traces
    public PaymentGatewayException(String message, int httpStatusCode, Throwable cause) {
        super(message, cause); // passes the original exception up the chain
        this.httpStatusCode = httpStatusCode;
    }

    public int getHttpStatusCode() {
        return httpStatusCode;
    }
}

// ── Unchecked: programming contract violation, not environmental failure ──
class InvalidOrderStateException extends RuntimeException {

    private final String fromState;
    private final String toState;

    public InvalidOrderStateException(String fromState, String toState) {
        super(String.format(
            "Illegal state transition: cannot move order from [%s] to [%s]",
            fromState, toState
        ));
        this.fromState = fromState;
        this.toState   = toState;
    }

    public String getFromState() { return fromState; }
    public String getToState()   { return toState;   }
}

// ── Service that uses both ──
class OrderService {

    enum OrderStatus { PENDING, CONFIRMED, SHIPPED, DELIVERED }

    // 'throws PaymentGatewayException' is REQUIRED by the compiler
    // because PaymentGatewayException is checked. This is the contract
    // telling every caller: handle the gateway being unavailable.
    public void chargeCustomer(String customerId, double amountInDollars)
            throws PaymentGatewayException {

        boolean gatewayReachable = simulateGatewayCall();

        if (!gatewayReachable) {
            // Wrap the low-level HTTP detail with a meaningful domain exception
            throw new PaymentGatewayException(
                "Payment gateway timed out for customer: " + customerId,
                504
            );
        }
        System.out.println("Charged $" + amountInDollars + " to customer " + customerId);
    }

    // No 'throws' declaration needed — unchecked exceptions are silent contracts
    public void transitionOrderStatus(OrderStatus current, OrderStatus next) {

        // SHIPPED → PENDING is a programmer error, not an environmental condition
        if (current == OrderStatus.SHIPPED && next == OrderStatus.PENDING) {
            throw new InvalidOrderStateException(current.name(), next.name());
        }
        System.out.println("Order moved: " + current + " → " + next);
    }

    private boolean simulateGatewayCall() {
        return false; // simulating an unreachable gateway
    }
}

public class CustomExceptionDesign {

    public static void main(String[] args) {

        OrderService orderService = new OrderService();

        // Checked exception — compiler REQUIRES this try-catch
        try {
            orderService.chargeCustomer("CUST-9912", 149.99);
        } catch (PaymentGatewayException paymentException) {
            // Caller handles the recoverable failure: maybe retry, or alert the user
            System.out.println("Payment failed (HTTP " + paymentException.getHttpStatusCode()
                + "): " + paymentException.getMessage());
            System.out.println("Queuing payment for retry...");
        }

        // Unchecked exception — no try-catch required by compiler
        // Only catch it at your application's outermost error boundary
        orderService.transitionOrderStatus(
            OrderService.OrderStatus.CONFIRMED,
            OrderService.OrderStatus.SHIPPED
        );

        // This next line would throw InvalidOrderStateException at runtime
        // because SHIPPED → PENDING is a logic bug in the calling code
        try {
            orderService.transitionOrderStatus(
                OrderService.OrderStatus.SHIPPED,
                OrderService.OrderStatus.PENDING
            );
        } catch (InvalidOrderStateException stateException) {
            System.out.println("Bug caught: " + stateException.getMessage());
        }
    }
}

import java.sql.*;

// ── Domain-level unchecked exception — service layer speaks in domain terms ──
class UserRepositoryException extends RuntimeException {
    public UserRepositoryException(String message, Throwable cause) {
        super(message, cause); // ALWAYS preserve the cause for stack trace logging
    }
}

class UserNotFoundException extends RuntimeException {
    private final long userId;
    public UserNotFoundException(long userId) {
        super("No user found with ID: " + userId);
        this.userId = userId;
    }
    public long getUserId() { return userId; }
}

// ── Infrastructure layer: wraps checked JDBC exceptions into unchecked domain ones ──
class UserRepository {

    private final Connection databaseConnection;

    public UserRepository(Connection databaseConnection) {
        this.databaseConnection = databaseConnection;
    }

    public String findUsernameById(long userId) {
        String query = "SELECT username FROM users WHERE id = ?";

        try {
            PreparedStatement statement = databaseConnection.prepareStatement(query);
            statement.setLong(1, userId);
            ResultSet results = statement.executeQuery();

            if (!results.next()) {
                // Business rule violation — unchecked, the caller should validate input
                throw new UserNotFoundException(userId);
            }

            return results.getString("username");

        } catch (SQLException sqlException) {
            // KEY PATTERN: catch the infrastructure checked exception here,
            // wrap it in our domain unchecked exception, preserve the cause.
            // The service layer never sees SQLException — it stays decoupled.
            throw new UserRepositoryException(
                "Database error while fetching user ID: " + userId,
                sqlException // <-- cause preserved for logging
            );
        }
    }
}

// ── Service layer: clean business logic, no SQL concerns ──
class UserProfileService {

    private final UserRepository userRepository;

    public UserProfileService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    // Notice: no 'throws' clause. The service layer is clean.
    // If UserRepositoryException propagates, the controller's global
    // error handler catches it and returns a 500. Clean separation.
    public String buildWelcomeMessage(long userId) {
        String username = userRepository.findUsernameById(userId); // no try-catch needed
        return "Welcome back, " + username + "!";
    }
}

// ── Presentation layer: only catches what it can meaningfully respond to ──
class UserController {

    private final UserProfileService profileService;

    public UserController(UserProfileService profileService) {
        this.profileService = profileService;
    }

    public String handleGetProfile(long userId) {
        try {
            return profileService.buildWelcomeMessage(userId);
        } catch (UserNotFoundException notFoundException) {
            // Caught specifically — return a 404 response
            return "404: User " + notFoundException.getUserId() + " not found";
        }
        // UserRepositoryException (database failure) is NOT caught here.
        // It propagates to the framework's global exception handler → 500 response.
        // That's the correct behaviour: the controller can't fix a database outage.
    }
}

public class LayeredExceptionPattern {

    public static void main(String[] args) throws Exception {
        // Simulate the lookup of a non-existent user (no real DB needed)
        // We'll mock the behaviour directly to show the flow

        // Simulating UserNotFoundException path
        UserController controller = buildMockController(false);
        String response = controller.handleGetProfile(99L);
        System.out.println("Controller response: " + response);
    }

    // Creates a controller backed by a fake repository for demo purposes
    static UserController buildMockController(boolean userExists) {
        UserRepository mockRepo = new UserRepository(null) {
            @Override
            public String findUsernameById(long userId) {
                if (!userExists) {
                    throw new UserNotFoundException(userId);
                }
                return "alice";
            }
        };
        return new UserController(new UserProfileService(mockRepo));
    }
}

import java.io.*;
import java.util.logging.*;

public class ExceptionMistakesAndFixes {

    private static final Logger logger =
        Logger.getLogger(ExceptionMistakesAndFixes.class.getName());

    // ════════════════════════════════════
    // MISTAKE 1: Swallowing the exception
    // ════════════════════════════════════

    static void badReadFile(String filePath) {
        try {
            new FileInputStream(filePath);
        } catch (FileNotFoundException e) {
            // ❌ WRONG: empty catch block. The failure disappears.
            // The caller gets null behaviour with zero explanation.
        }
    }

    static void goodReadFile(String filePath) throws FileNotFoundException {
        try {
            new FileInputStream(filePath);
        } catch (FileNotFoundException fileNotFoundException) {
            // ✅ RIGHT: log it, then either handle it or rethrow
            logger.severe("Cannot open config file at: " + filePath);
            throw fileNotFoundException; // rethrow so the caller knows
        }
    }

    // ═══════════════════════════════════════════════
    // MISTAKE 2: Catching Exception too broadly
    // ═══════════════════════════════════════════════

    static void badBroadCatch(String[] items, int index, String filePath) {
        try {
            String item   = items[index];          // might throw ArrayIndexOutOfBoundsException
            new FileInputStream(filePath);         // might throw FileNotFoundException
            Integer.parseInt(item);                // might throw NumberFormatException
        } catch (Exception e) {
            // ❌ WRONG: all three failures look identical here.
            // A bug in your index logic is hidden alongside a missing file.
            System.out.println("Something failed: " + e.getMessage());
        }
    }

    static void goodSpecificCatch(String[] items, int index, String filePath) {
        // ✅ RIGHT: handle each failure mode where you can act on it specifically
        if (index < 0 || index >= items.length) {
            // Validate input before use — don't rely on catching your own bug
            throw new IllegalArgumentException(
                "Index " + index + " is out of range for array of size " + items.length
            );
        }

        String item = items[index];

        try {
            new FileInputStream(filePath);
        } catch (FileNotFoundException fileNotFoundException) {
            logger.warning("File not found: " + filePath);
            // Handle the file-missing case specifically — maybe use a default
        }

        try {
            Integer.parseInt(item);
        } catch (NumberFormatException numberFormatException) {
            logger.warning("Item '" + item + "' is not a valid integer");
            // Handle the bad-format case specifically
        }
    }

    // ═══════════════════════════════════════════════════════
    // MISTAKE 3: Losing the original cause when wrapping
    // ═══════════════════════════════════════════════════════

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

    static void badWrap(String filePath) {
        try {
            new FileInputStream(filePath);
        } catch (FileNotFoundException fileNotFoundException) {
            // ❌ WRONG: the original FileNotFoundException and its stack
            // trace are thrown away. In production logs, you'll only see
            // DataLoadException with no trace back to the root cause.
            throw new DataLoadException("Could not load data", null);
        }
    }

    static void goodWrap(String filePath) {
        try {
            new FileInputStream(filePath);
        } catch (FileNotFoundException fileNotFoundException) {
            // ✅ RIGHT: pass the original exception as the cause.
            // Both exceptions appear in the stack trace.
            throw new DataLoadException(
                "Could not load data from: " + filePath,
                fileNotFoundException // <-- cause preserved
            );
        }
    }

    public static void main(String[] args) {
        // Demonstrate the cause-preservation difference
        try {
            goodWrap("/no/such/file.csv");
        } catch (DataLoadException dataLoadException) {
            System.out.println("Top-level message: " + dataLoadException.getMessage());
            System.out.println("Root cause:        " + dataLoadException.getCause().getMessage());
        }
    }
}