Java Exception Handling Explained — try, catch, finally and Real-World Patterns

public class ExceptionHierarchyDemo {

    public static void main(String[] args) {

        // --- Unchecked (RuntimeException) ---
        // No compiler warning. These represent programming mistakes.
        demonstrateUnchecked();

        // --- Checked (Exception) ---
        // Compiler FORCES you to handle this. Represents foreseeable external failures.
        demonstrateChecked();
    }

    static void demonstrateUnchecked() {
        int[] temperatures = {72, 68, 75};

        try {
            // Accessing index 5 on a 3-element array — a programming mistake
            int invalidReading = temperatures[5];
        } catch (ArrayIndexOutOfBoundsException exception) {
            // We catch it here to demo the output, but in real code
            // you'd fix the logic instead of catching this
            System.out.println("[Unchecked] Caught: " + exception.getMessage());
            System.out.println("Fix the index, don't catch this in production.");
        }
    }

    static void demonstrateChecked() {
        // java.io.FileReader throws the CHECKED IOException
        // The compiler won't let you call it without handling it
        try {
            java.io.FileReader configFile = new java.io.FileReader("/etc/app/config.properties");
            System.out.println("Config file opened successfully.");
            configFile.close();
        } catch (java.io.IOException ioException) {
            // This is a legitimate runtime condition — the file may not exist
            // on this machine. Handling it is the RIGHT response.
            System.out.println("[Checked] Caught: " + ioException.getMessage());
            System.out.println("Falling back to default configuration.");
        }
    }
}

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;
import java.io.StringReader;

public class ResourceManagementDemo {

    public static void main(String[] args) {
        System.out.println("=== Old-style try-finally ===");
        readWithTryFinally();

        System.out.println("\n=== Modern try-with-resources ===");
        readWithTryWithResources();

        System.out.println("\n=== Execution order demo ===");
        System.out.println("Result: " + executionOrderDemo());
    }

    // OLD WAY — verbose and error-prone
    static void readWithTryFinally() {
        BufferedReader reader = null;
        try {
            // Using StringReader to simulate file reading without needing an actual file
            reader = new BufferedReader(new StringReader("order_id=12345\namount=99.99"));
            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println("Read: " + line);
            }
        } catch (IOException ioException) {
            System.out.println("Failed to read data: " + ioException.getMessage());
        } finally {
            // Must manually null-check before closing
            if (reader != null) {
                try {
                    reader.close(); // close() itself throws IOException — nested try!
                    System.out.println("Reader closed manually.");
                } catch (IOException closeException) {
                    System.out.println("Failed to close reader: " + closeException.getMessage());
                }
            }
        }
    }

    // MODERN WAY — cleaner, safer, suppressed exceptions handled correctly
    static void readWithTryWithResources() {
        // BufferedReader implements AutoCloseable, so it's valid here
        // Java closes it automatically when the block exits, in any scenario
        try (BufferedReader reader = new BufferedReader(
                new StringReader("order_id=67890\namount=149.50"))) {

            String line;
            while ((line = reader.readLine()) != null) {
                System.out.println("Read: " + line);
            }
            // No finally needed — reader.close() is called automatically here

        } catch (IOException ioException) {
            System.out.println("Failed to read data: " + ioException.getMessage());
        }
        System.out.println("Reader closed automatically by try-with-resources.");
    }

    // Demonstrates that finally runs even when catch runs, and BEFORE the return
    static String executionOrderDemo() {
        try {
            System.out.println("1. try block runs");
            int result = 10 / 0; // Triggers ArithmeticException
            return "unreachable"; // Never executes
        } catch (ArithmeticException exception) {
            System.out.println("2. catch block runs: " + exception.getMessage());
            return "from catch"; // This return is PAUSED until finally completes
        } finally {
            // This ALWAYS runs — even though catch has a return statement
            System.out.println("3. finally block runs last");
            // WARNING: if you put 'return "from finally"' here,
            // it would override the catch's return — silently. Don't do it.
        }
    }
}

// === Custom Exception Definitions ===

// Checked — callers MUST handle payment failures. It's part of our API contract.
class PaymentDeclinedException extends Exception {

    private final String declineCode;   // Machine-readable code from the payment gateway
    private final String cardLastFour;  // For logging without storing full PAN

    // Constructor for when we originate the exception ourselves
    public PaymentDeclinedException(String message, String declineCode, String cardLastFour) {
        super(message);
        this.declineCode = declineCode;
        this.cardLastFour = cardLastFour;
    }

    // Constructor for wrapping a lower-level exception (preserves root cause in logs)
    public PaymentDeclinedException(String message, String declineCode,
                                    String cardLastFour, Throwable cause) {
        super(message, cause); // 'cause' appears in stack trace as "Caused by:"
        this.declineCode = declineCode;
        this.cardLastFour = cardLastFour;
    }

    public String getDeclineCode() { return declineCode; }
    public String getCardLastFour() { return cardLastFour; }
}

// Unchecked — a programming/config error, not a recoverable runtime condition
class PaymentGatewayConfigException extends RuntimeException {
    public PaymentGatewayConfigException(String message) {
        super(message);
    }
    public PaymentGatewayConfigException(String message, Throwable cause) {
        super(message, cause);
    }
}

// === Service Layer ===

class PaymentService {

    private final String gatewayApiKey;

    public PaymentService(String gatewayApiKey) {
        // Validate config at construction time — fail fast with an unchecked exception
        if (gatewayApiKey == null || gatewayApiKey.isBlank()) {
            throw new PaymentGatewayConfigException(
                "Payment gateway API key is missing. Check application.properties."
            );
        }
        this.gatewayApiKey = gatewayApiKey;
    }

    // Checked exception declared in signature — callers see this is a real risk
    public String processPayment(double amountInDollars, String cardLastFour)
            throws PaymentDeclinedException {

        // Simulating a gateway decline for cards ending in 0000
        if (cardLastFour.equals("0000")) {
            throw new PaymentDeclinedException(
                "Card declined: insufficient funds",
                "INSUFFICIENT_FUNDS",
                cardLastFour
            );
        }

        // Simulating a low-level exception from a gateway library
        if (amountInDollars > 10000.0) {
            Exception gatewayLimitError = new Exception("Gateway hard limit exceeded: $10,000");
            throw new PaymentDeclinedException(
                "Transaction exceeds per-charge limit",
                "LIMIT_EXCEEDED",
                cardLastFour,
                gatewayLimitError  // Original cause preserved — shows up in stack trace
            );
        }

        return "TXN-" + System.currentTimeMillis();
    }
}

// === Main Demo ===

public class PaymentProcessingDemo {

    public static void main(String[] args) {

        // This would throw PaymentGatewayConfigException (unchecked) immediately
        // PaymentService badService = new PaymentService("");

        PaymentService paymentService = new PaymentService("sk_live_abc123");

        // Scenario 1: Successful payment
        processOrder(paymentService, 49.99, "4242");

        // Scenario 2: Declined card
        processOrder(paymentService, 49.99, "0000");

        // Scenario 3: Amount over limit
        processOrder(paymentService, 15000.00, "1234");
    }

    static void processOrder(PaymentService service, double amount, String cardLastFour) {
        System.out.println("\nProcessing $" + amount + " on card ending " + cardLastFour);
        try {
            String transactionId = service.processPayment(amount, cardLastFour);
            System.out.println("  SUCCESS — Transaction ID: " + transactionId);

        } catch (PaymentDeclinedException declineException) {
            // Structured data lets us respond intelligently
            System.out.println("  DECLINED — Code: " + declineException.getDeclineCode());
            System.out.println("  Message: " + declineException.getMessage());

            // If there was a root cause, log it for the ops team
            if (declineException.getCause() != null) {
                System.out.println("  Root cause: " + declineException.getCause().getMessage());
            }
        }
    }
}

import java.io.IOException;
import java.sql.SQLException;

public class ExceptionPropagationDemo {

    public static void main(String[] args) {
        // Top-level handler — catches anything that propagated up uncaught
        try {
            runNightlyReport();
        } catch (ReportGenerationException reportException) {
            System.out.println("[MAIN] Report pipeline failed: " + reportException.getMessage());
            if (reportException.getCause() != null) {
                System.out.println("[MAIN] Root cause: " + reportException.getCause().getMessage());
            }
        }

        System.out.println("\n--- Multi-catch demo ---");
        demonstrateMultiCatch(true, false);  // Trigger IOException path
        demonstrateMultiCatch(false, true);  // Trigger SQLException path
        demonstrateMultiCatch(false, false); // Happy path
    }

    // This method declares 'throws' — it doesn't handle the failure, it passes it up
    static void fetchDataFromDatabase(boolean simulateFailure) throws SQLException {
        if (simulateFailure) {
            // Simulating a real SQL error (e.g., connection dropped mid-query)
            throw new SQLException("Connection reset by peer during query execution");
        }
        System.out.println("  [DB] Fetched 1,542 sales records.");
    }

    // This method also propagates — it wraps the original into a domain exception
    static void generateReport(boolean dbFailure) throws ReportGenerationException {
        try {
            fetchDataFromDatabase(dbFailure); // checked exception propagated from here
            System.out.println("  [Report] Report generated successfully.");
        } catch (SQLException sqlException) {
            // We catch the low-level error and re-throw as a domain exception
            // The original sqlException is preserved as the cause — critical for debugging
            throw new ReportGenerationException(
                "Unable to generate nightly report — database read failed",
                sqlException
            );
        }
    }

    static void runNightlyReport() throws ReportGenerationException {
        System.out.println("Starting nightly report pipeline...");
        generateReport(true); // Simulate DB failure
    }

    // Multi-catch: same response to different exception types
    static void demonstrateMultiCatch(boolean triggerIO, boolean triggerSQL) {
        try {
            if (triggerIO) {
                // IOException is checked — would need throws or try-catch
                throw new IOException("Report output directory is read-only");
            }
            if (triggerSQL) {
                throw new SQLException("Deadlock detected on report_summary table");
            }
            System.out.println("  [Multi-catch] Operation completed without errors.");

        } catch (IOException | SQLException infrastructureException) {
            // Multi-catch: both exceptions get identical treatment here — log and alert
            // Note: 'infrastructureException' is effectively final in this block
            System.out.println("  [Multi-catch] Infrastructure error — paging on-call engineer.");
            System.out.println("  Detail: " + infrastructureException.getMessage());

        } catch (Exception unexpectedException) {
            // Catch-all MUST come after specific catches, or compiler complains
            System.out.println("  [Multi-catch] Unexpected error: " + unexpectedException.getMessage());
        }
    }
}

// Domain exception — wraps infrastructure failures with business context
class ReportGenerationException extends Exception {
    public ReportGenerationException(String message, Throwable cause) {
        super(message, cause);
    }
}