Java try-catch-finally — The Silent Connection Leak Pattern

package io.thecodeforge.exception;

public class ExceptionFlowDemo {

    public static void main(String[] args) {
        System.out.println("=== Scenario 1: No exception — happy path ===");
        readUserAge("25");

        System.out.println("\n=== Scenario 2: Recoverable exception caught ===");
        readUserAge("twenty");

        System.out.println("\n=== Scenario 3: Exception propagates — finally still runs ===");
        try {
            riskyDivision(10, 0);
        } catch (ArithmeticException ex) {
            // finally in riskyDivision ran BEFORE this catch executes
            System.out.println("Caught in main: " + ex.getMessage());
        }

        System.out.println("\n=== Scenario 4: return inside try — finally still runs ===");
        int result = earlyReturn(true);
        System.out.println("Returned: " + result);
    }

    static void readUserAge(String input) {
        System.out.println("Attempting to parse: " + input);
        try {
            int age = Integer.parseInt(input);
            System.out.println("Parsed age: " + age);
        } catch (NumberFormatException ex) {
            System.out.println("Bad input — could not parse '" + input + "' as a number.");
        } finally {
            // Runs whether parsing succeeded or threw
            System.out.println("finally executed for input: '" + input + "'");
        }
    }

    static int riskyDivision(int numerator, int denominator) {
        System.out.println("Inside riskyDivision — about to divide.");
        try {
            int result = numerator / denominator;
            System.out.println("Result: " + result);
            return result;
        } finally {
            // Runs before the ArithmeticException reaches main's catch block
            System.out.println("riskyDivision finally — runs before exception reaches caller.");
        }
    }

    static int earlyReturn(boolean condition) {
        try {
            if (condition) {
                System.out.println("try: returning 42");
                return 42;
            }
            return 0;
        } finally {
            // finally runs even though try has a return statement
            // NOTE: do NOT add 'return' here — it would silently override 42
            System.out.println("finally: cleanup before actual return");
        }
    }
}

package io.thecodeforge.exception;

import java.io.*;
import java.nio.file.*;
import java.util.logging.Logger;

public class ConfigFileReader {

    private static final Logger log = Logger.getLogger(ConfigFileReader.class.getName());

    public static void main(String[] args) {
        System.out.println("Port: " + readPort("missing.props"));
        System.out.println("Port: " + readPort("corrupt.props"));
    }

    /**
     * Reads a port number from a properties file.
     * Demonstrates: ordered catch blocks, multi-catch, and the catch-specific rule.
     */
    static int readPort(String filePath) {
        try {
            String content = Files.readString(Path.of(filePath)).trim();
            return Integer.parseInt(content);

        } catch (NoSuchFileException e) {
            // Most specific IOException subtype — file simply does not exist.
            // Recoverable: use the default port.
            log.warning("Config file not found: " + filePath + " — using default port 8080");
            return 8080;

        } catch (AccessDeniedException e) {
            // Also a specific IOException subtype — different root cause, different message.
            log.severe("Permission denied reading: " + filePath + " — check file ownership");
            return -1;

        } catch (IOException | NumberFormatException e) {
            // Multi-catch: IOException (other IO failures) and NumberFormatException are
            // unrelated by inheritance — valid multi-catch candidates.
            // Same recovery: log, return sentinel.
            log.warning("Failed to load config from " + filePath + ": " + e.getMessage());
            return -1;

        } finally {
            System.out.println("Config read attempted for: " + filePath);
        }
    }

    /*
     * WRONG — do not do this. Demonstrated here so you recognise it.
     * Catching Throwable includes OutOfMemoryError, StackOverflowError,
     * and every Error subclass. The JVM may be in a corrupt state.
     * Continuing after this catch produces silently wrong results.
     *
     * static int readPortDangerous(String filePath) {
     *     try {
     *         return Integer.parseInt(Files.readString(Path.of(filePath)).trim());
     *     } catch (Throwable t) {
     *         // 'Pokemon' handling — catches everything, handles nothing safely
     *         return -1;
     *     }
     * }
     */
}

package io.thecodeforge.exception;

import java.sql.SQLException;
import java.util.logging.Logger;

/**
 * Demonstrates exception chaining across layers and custom exception design.
 *
 * Layer structure:
 *   UserRepository (data layer) — throws SQLException
 *   UserService    (service layer) — translates to domain exception
 *   UserController (API layer) — handles domain exception
 */
public class ExceptionChainingDemo {

    private static final Logger log = Logger.getLogger(ExceptionChainingDemo.class.getName());

    // ----------------------------------------------------------------
    // Custom exception — carries structured context, not just a string
    // ----------------------------------------------------------------
    static class UserNotFoundException extends RuntimeException {
        private final int userId;

        UserNotFoundException(int userId, String message, Throwable cause) {
            super(message, cause);  // cause chain preserved here
            this.userId = userId;
        }

        int getUserId() { return userId; }
    }

    // ----------------------------------------------------------------
    // Sealed exception hierarchy (Java 17+)
    // Compiler knows exhaustively which subtypes exist.
    // Useful when combined with pattern matching in catch (Java 21+).
    // ----------------------------------------------------------------
    sealed interface PaymentException permits PaymentException.Declined, PaymentException.NetworkTimeout {
        record Declined(String reason, int statusCode) implements PaymentException, RuntimeException {
            public Declined { super(); }
        }
        record NetworkTimeout(String host, int timeoutMs) implements PaymentException, RuntimeException {
            public NetworkTimeout { super(); }
        }
    }

    // ----------------------------------------------------------------
    // Data layer — throws low-level checked exception
    // ----------------------------------------------------------------
    static String findUserInDatabase(int userId) throws SQLException {
        // Simulated: database returns no row for userId 99
        if (userId == 99) {
            throw new SQLException("No row returned for user_id=" + userId, "02000");
        }
        return "Alice";
    }

    // ----------------------------------------------------------------
    // Service layer — translates to domain exception, chains cause
    // ----------------------------------------------------------------
    static String lookupUser(int userId) {
        try {
            return findUserInDatabase(userId);
        } catch (SQLException e) {
            // WRONG (shown for contrast): throw new UserNotFoundException(userId, "Not found", null);
            // The null cause discards the original SQLException — no SQL state, no stack trace.

            // CORRECT: chain the original exception as cause
            throw new UserNotFoundException(
                userId,
                "User " + userId + " not found in database",
                e  // original SQLException preserved as getCause()
            );
        }
    }

    // ----------------------------------------------------------------
    // API layer — handles domain exception, has full chain for logging
    // ----------------------------------------------------------------
    public static void main(String[] args) {
        // Scenario 1: successful lookup
        System.out.println("=== Scenario 1: found ===");
        System.out.println(lookupUser(1));

        // Scenario 2: user not found — exception chain visible
        System.out.println("\n=== Scenario 2: not found — inspect cause chain ===");
        try {
            lookupUser(99);
        } catch (UserNotFoundException e) {
            // Domain-level: structured context available
            System.out.println("Domain error: " + e.getMessage());
            System.out.println("User ID from exception: " + e.getUserId());

            // Root cause: original low-level detail preserved
            Throwable cause = e.getCause();
            if (cause != null) {
                System.out.println("Root cause type: " + cause.getClass().getSimpleName());
                System.out.println("Root cause message: " + cause.getMessage());
            }

            // In production: pass 'e' to logger — SLF4J/Log4j2 prints the full chain
            log.severe("User lookup failed: " + e.getMessage() + " caused by: " + cause);
        }

        // Scenario 3: wrong pattern — cause discarded
        System.out.println("\n=== Scenario 3: wrong pattern — root cause lost ===");
        try {
            try {
                findUserInDatabase(99);
            } catch (SQLException e) {
                // WRONG: only passing message string — root cause is permanently gone
                throw new RuntimeException("User not found");
            }
        } catch (RuntimeException e) {
            System.out.println("Exception message: " + e.getMessage());
            System.out.println("Cause: " + e.getCause()); // null — gone forever
        }
    }
}

package io.thecodeforge.exception;

import java.io.*;
import java.nio.file.*;
import java.sql.*;
import java.util.logging.Logger;

public class ResourceCleanup {

    private static final Logger log = Logger.getLogger(ResourceCleanup.class.getName());

    public static void main(String[] args) throws Exception {
        System.out.println("=== try-with-resources: single resource ===");
        readFirstLine("forge.txt");

        System.out.println("\n=== try-with-resources: multiple resources (close in reverse order) ===");
        queryDatabase();

        System.out.println("\n=== Manual finally: suppressed exception demo ===");
        demonstrateSuppressedExceptions();
    }

    // ----------------------------------------------------------------
    // Pattern 1: try-with-resources — single AutoCloseable
    // ----------------------------------------------------------------
    static void readFirstLine(String path) {
        // BufferedReader implements AutoCloseable — close() called automatically
        try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
            System.out.println("First line: " + reader.readLine());
        } catch (FileNotFoundException e) {
            log.warning("File not found: " + path);
        } catch (IOException e) {
            log.severe("IO error reading " + path + ": " + e.getMessage());
        }
        // reader.close() guaranteed here — no finally block needed
    }

    // ----------------------------------------------------------------
    // Pattern 2: multiple resources — close in reverse declaration order
    // stmt closes before conn — correct JDBC teardown sequence
    // ----------------------------------------------------------------
    static void queryDatabase() throws Exception {
        // In-memory H2 for demonstration; works with any JDBC DataSource
        try (Connection conn = DriverManager.getConnection("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1");
             PreparedStatement stmt = conn.prepareStatement("SELECT 1 AS result")) {

            ResultSet rs = stmt.executeQuery();
            if (rs.next()) {
                System.out.println("Query result: " + rs.getInt("result"));
            }
            // stmt closes first, then conn — reverse of declaration order
        } catch (SQLException e) {
            log.severe("Database error: " + e.getMessage());
            throw e;
        }
    }

    // ----------------------------------------------------------------
    // Pattern 3: suppressed exceptions — what try-with-resources preserves
    // ----------------------------------------------------------------
    static void demonstrateSuppressedExceptions() {
        // Simulate a resource where both the body and close() throw
        AutoCloseable noisyResource = () -> {
            throw new IOException("close() failed — secondary error");
        };

        try (var resource = noisyResource) {
            throw new RuntimeException("primary business logic failure");
            // When this block throws AND close() throws:
            // - primary exception: RuntimeException is preserved
            // - close() IOException is attached as suppressed — not discarded
        } catch (RuntimeException e) {
            System.out.println("Primary: " + e.getMessage());
            for (Throwable suppressed : e.getSuppressed()) {
                // The close() failure is accessible here — nothing was lost
                System.out.println("Suppressed (from close): " + suppressed.getMessage());
            }
        } catch (Exception e) {
            log.severe("Unexpected: " + e.getMessage());
        }
    }

    // ----------------------------------------------------------------
    // Manual finally — only when AutoCloseable is not available
    // Guard every resource access with null check
    // ----------------------------------------------------------------
    static void legacyCleanupPattern(String path) {
        BufferedReader reader = null; // initialise to null — guards the finally check
        try {
            reader = new BufferedReader(new FileReader(path));
            System.out.println(reader.readLine());
        } catch (IOException e) {
            log.warning("IO error: " + e.getMessage());
        } finally {
            if (reader != null) { // without this, NullPointerException if open() threw
                try {
                    reader.close();
                } catch (IOException closeEx) {
                    // Log the close failure but do not let it propagate —
                    // we do not want the close exception to replace any original exception
                    log.warning("Failed to close reader: " + closeEx.getMessage());
                }
            }
        }
    }
}

package io.thecodeforge.exception;

public class FinallyReturnGotcha {

    public static void main(String[] args) {
        System.out.println("=== Scenario 1: finally return overrides try return ===");
        System.out.println("Bonus: " + calculateBonusWrong(true));   // Expect 500, get -1
        System.out.println("Bonus: " + calculateBonusCorrect(true)); // Correct: 500

        System.out.println("\n=== Scenario 2: finally throw discards original exception ===");
        try {
            riskyWithFinallyThrow();
        } catch (Exception e) {
            System.out.println("Caught: " + e.getMessage());
            System.out.println("Cause: " + e.getCause()); // null — original is gone
        }

        System.out.println("\n=== Scenario 3: correct pattern — no return in finally ===");
        try {
            riskyCorrect();
        } catch (Exception e) {
            System.out.println("Caught: " + e.getMessage());
            System.out.println("Cause: " + e.getCause()); // original cause preserved
        }
    }

    // WRONG: return in finally silently overrides try's return
    static int calculateBonusWrong(boolean eligible) {
        try {
            if (eligible) {
                System.out.println("try: returning 500");
                return 500; // computed and stored temporarily
            }
            return 0;
        } finally {
            System.out.println("finally: overriding with -1");
            return -1; // silently replaces 500 — no warning from the compiler
        }
    }

    // CORRECT: finally for cleanup only, return stays in try
    static int calculateBonusCorrect(boolean eligible) {
        try {
            if (eligible) {
                System.out.println("try: returning 500");
                return 500;
            }
            return 0;
        } finally {
            // Cleanup only — no return here
            System.out.println("finally: cleanup only");
        }
    }

    // WRONG: throw in finally discards the original exception entirely
    static void riskyWithFinallyThrow() throws Exception {
        try {
            throw new IllegalStateException("original failure — this gets lost");
        } finally {
            // This throw replaces the IllegalStateException permanently
            // getCause() on the caught exception will be null
            throw new RuntimeException("cleanup failure — this is all the caller sees");
        }
    }

    // CORRECT: wrap cleanup in its own try-catch inside finally
    static void riskyCorrect() throws Exception {
        try {
            throw new IllegalStateException("original failure — preserved as cause");
        } finally {
            try {
                // Simulated cleanup that could fail
                performCleanup();
            } catch (Exception cleanupEx) {
                // Log the cleanup failure but do not propagate it —
                // the original IllegalStateException continues to propagate
                System.out.println("Cleanup failed (logged, not rethrown): " + cleanupEx.getMessage());
            }
        }
    }

    static void performCleanup() throws Exception {
        throw new IOException("cleanup step failed");
    }
}

package io.thecodeforge.exception;

import java.io.*;
import java.sql.SQLException;
import java.util.logging.Logger;

public class ThrowsDeclarationDemo {

    private static final Logger log = Logger.getLogger(ThrowsDeclarationDemo.class.getName());

    // ----------------------------------------------------------------
    // Custom checked exception — forces callers to make a decision
    // Use when the caller can meaningfully recover
    // ----------------------------------------------------------------
    static class ConfigNotFoundException extends Exception {
        private final String configKey;

        ConfigNotFoundException(String configKey, String message) {
            super(message);
            this.configKey = configKey;
        }

        ConfigNotFoundException(String configKey, String message, Throwable cause) {
            super(message, cause); // chained cause preserved
            this.configKey = configKey;
        }

        String getConfigKey() { return configKey; }
    }

    // ----------------------------------------------------------------
    // Custom unchecked exception — for unrecoverable or programming errors
    // Use when the caller cannot meaningfully recover
    // ----------------------------------------------------------------
    static class DataLayerException extends RuntimeException {
        DataLayerException(String message, Throwable cause) {
            super(message, cause);
        }
    }

    // ----------------------------------------------------------------
    // throws clause: declaring a checked exception
    // Caller is forced by the compiler to handle or redeclare
    // ----------------------------------------------------------------
    static String loadConfigValue(String key) throws ConfigNotFoundException {
        // Simulated: key not found in config store
        if ("missing.key".equals(key)) {
            throw new ConfigNotFoundException(key,
                "Configuration key '" + key + "' not found in config store");
        }
        return "production-value";
    }

    // ----------------------------------------------------------------
    // Wrapping a checked exception in unchecked — the Spring pattern
    // Checked exception is chained as cause — not discarded
    // ----------------------------------------------------------------
    static String loadFromDatabase(int id) {
        try {
            // Simulated JDBC call that throws checked SQLException
            if (id < 0) throw new SQLException("Invalid id: " + id);
            return "record-" + id;
        } catch (SQLException e) {
            // Translate to unchecked — removes throws from signature
            // but preserves original cause for diagnosis
            throw new DataLayerException("Failed to load record " + id, e);
        }
    }

    // ----------------------------------------------------------------
    // Caller handling a checked exception — forced by throws clause
    // ----------------------------------------------------------------
    static void callWithCheckedHandling() {
        try {
            String value = loadConfigValue("missing.key"); // compiler requires try-catch here
            System.out.println("Value: " + value);
        } catch (ConfigNotFoundException e) {
            System.out.println("Handled: " + e.getMessage());
            System.out.println("Missing key: " + e.getConfigKey());
        }
    }

    // ----------------------------------------------------------------
    // Redeclaring — passing the obligation up the call stack
    // ----------------------------------------------------------------
    static void redeclareToCallerMethod() throws ConfigNotFoundException {
        // Not handling here — redeclaring forces the caller to handle it
        String value = loadConfigValue("another.missing.key");
        System.out.println(value);
    }

    public static void main(String[] args) {
        System.out.println("=== Checked exception: caller forced to handle ===");
        callWithCheckedHandling();

        System.out.println("\n=== Unchecked wrapping: cause chain preserved ===");
        try {
            loadFromDatabase(-1);
        } catch (DataLayerException e) {
            System.out.println("Domain: " + e.getMessage());
            System.out.println("Root cause: " + e.getCause().getMessage());
        }

        System.out.println("\n=== Redeclaring: obligation passed to main ===");
        try {
            redeclareToCallerMethod();
        } catch (ConfigNotFoundException e) {
            System.out.println("Caught at main: " + e.getMessage());
        }
    }
}

package io.thecodeforge.exception;

import java.util.concurrent.*;
import java.util.logging.Logger;

/**
 * Demonstrates exception handling with Java 21 virtual threads
 * and StructuredTaskScope.
 *
 * Requires: Java 21+ (StructuredTaskScope is a preview in 21, standard in later releases)
 * Compile: javac --enable-preview --release 21 ...
 */
public class VirtualThreadsAndStructuredConcurrency {

    private static final Logger log = Logger.getLogger(
        VirtualThreadsAndStructuredConcurrency.class.getName()
    );

    // ----------------------------------------------------------------
    // Pattern 1: UncaughtExceptionHandler for virtual threads
    // At virtual-thread scale, this is critical observability infrastructure
    // ----------------------------------------------------------------
    static void demonstrateVirtualThreadException() throws InterruptedException {
        Thread.UncaughtExceptionHandler handler = (thread, throwable) -> {
            // In production: log.error("Uncaught in virtual thread", throwable)
            System.out.println("[UncaughtHandler] Thread: " + thread.getName()
                + " threw: " + throwable.getMessage());
        };

        Thread virtualThread = Thread.ofVirtual()
            .name("payment-processor")
            .uncaughtExceptionHandler(handler)
            .start(() -> {
                System.out.println("[VirtualThread] Starting payment processing");
                // Simulated failure inside virtual thread
                throw new RuntimeException("Payment gateway unreachable");
            });

        virtualThread.join(); // wait for completion
        System.out.println("[Main] Virtual thread finished");
    }

    // ----------------------------------------------------------------
    // Pattern 2: StructuredTaskScope.ShutdownOnFailure
    // All tasks must succeed — first failure cancels the rest
    // ----------------------------------------------------------------
    static void fetchUserDashboard(int userId) throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {

            // Fork concurrent tasks — each runs on its own virtual thread
            StructuredTaskScope.Subtask<String> profileTask =
                scope.fork(() -> fetchUserProfile(userId));

            StructuredTaskScope.Subtask<Integer> orderCountTask =
                scope.fork(() -> fetchOrderCount(userId));

            // Wait for all tasks to complete or any to fail
            scope.join();

            // Re-raises the first exception if any task failed
            // Wraps it in ExecutionException — unwrap to get the original
            scope.throwIfFailed();

            // If we reach here, all tasks succeeded
            System.out.println("Profile: " + profileTask.get());
            System.out.println("Orders: " + orderCountTask.get());

        } catch (ExecutionException e) {
            // throwIfFailed() wraps the original — getCause() gives the real exception
            Throwable cause = e.getCause();
            System.out.println("Dashboard load failed: " + cause.getMessage());
            throw new RuntimeException("Failed to load dashboard for user " + userId, cause);
        }
    }

    // ----------------------------------------------------------------
    // Pattern 3: StructuredTaskScope.ShutdownOnSuccess
    // Return as soon as any task succeeds — first result wins
    // ----------------------------------------------------------------
    static String fetchFromFastestSource(String key) throws Exception {
        try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {

            scope.fork(() -> fetchFromPrimaryCache(key));
            scope.fork(() -> fetchFromSecondaryCache(key));
            scope.fork(() -> fetchFromDatabase(key));

            scope.join(); // wait for first success or all failures

            // Returns the first successful result
            return scope.result();

        } catch (ExecutionException e) {
            // All sources failed — getCause() has the last failure
            throw new RuntimeException("All sources failed for key: " + key, e.getCause());
        }
    }

    // Simulated service calls
    static String fetchUserProfile(int id) throws Exception {
        Thread.sleep(50);
        if (id == 0) throw new IllegalArgumentException("Invalid user id: " + id);
        return "Alice (id=" + id + ")";
    }

    static int fetchOrderCount(int id) throws Exception {
        Thread.sleep(30);
        return 42;
    }

    static String fetchFromPrimaryCache(String key) throws Exception {
        Thread.sleep(10);
        return "cached:" + key;
    }

    static String fetchFromSecondaryCache(String key) throws Exception {
        Thread.sleep(50);
        return "secondary:" + key;
    }

    static String fetchFromDatabase(String key) throws Exception {
        Thread.sleep(100);
        return "db:" + key;
    }

    public static void main(String[] args) throws Exception {
        System.out.println("=== Virtual thread uncaught exception ===");
        demonstrateVirtualThreadException();

        System.out.println("\n=== StructuredTaskScope.ShutdownOnFailure: all succeed ===");
        fetchUserDashboard(1);

        System.out.println("\n=== StructuredTaskScope.ShutdownOnFailure: one fails ===");
        fetchUserDashboard(0); // userId=0 triggers failure in fetchUserProfile

        System.out.println("\n=== StructuredTaskScope.ShutdownOnSuccess ===");
        String result = fetchFromFastestSource("config.timeout");
        System.out.println("Fastest result: " + result);
    }
}

package io.thecodeforge.exception;

import java.sql.*;
import java.util.Optional;
import java.util.logging.Logger;

public class BestPracticesDemo {

    private static final Logger log = Logger.getLogger(BestPracticesDemo.class.getName());

    // Injected via constructor — testable and self-contained
    private final DataSource dataSource;

    BestPracticesDemo(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    // ----------------------------------------------------------------
    // Pattern 1: try-with-resources + exception chaining + fail fast
    // ----------------------------------------------------------------
    public Optional<String> lookupUser(int userId) {
        try (Connection conn = dataSource.getConnection();
             PreparedStatement stmt = conn.prepareStatement(
                 "SELECT name FROM users WHERE id = ?")) {

            stmt.setInt(1, userId);
            ResultSet rs = stmt.executeQuery();

            if (rs.next()) {
                return Optional.of(rs.getString("name"));
            } else {
                // Expected: no record. Return empty — do not throw.
                // Exceptions are for exceptional conditions, not 'not found'.
                return Optional.empty();
            }

        } catch (SQLException e) {
            // Log the full exception object — not just e.getMessage()
            // The logger prints the full stack trace and cause chain automatically
            log.severe("Database error looking up userId=" + userId + ": " + e.getMessage());
            // Fail fast: rethrow wrapped — caller knows something went wrong
            // and the original SQLException is preserved as cause
            throw new DataLayerException("Failed to lookup user " + userId, e);
        }
    }

    // ----------------------------------------------------------------
    // Pattern 2: high-frequency exception — override fillInStackTrace()
    // Use when an exception is thrown in a hot path (e.g., parser loop)
    // and stack trace generation is a measured bottleneck
    // ----------------------------------------------------------------
    static class FastValidationException extends RuntimeException {
        FastValidationException(String message) {
            super(message);
        }

        @Override
        public synchronized Throwable fillInStackTrace() {
            // Skip stack trace generation — reduces cost from O(depth) to O(1)
            // Trade-off: no stack trace in logs. Use only when profiling confirms
            // stack trace generation is a measured hotspot.
            return this;
        }
    }

    // ----------------------------------------------------------------
    // Pattern 3: Optional instead of exception for expected absence
    // ----------------------------------------------------------------
    static Optional<Integer> parsePort(String value) {
        try {
            int port = Integer.parseInt(value);
            if (port < 1 || port > 65535) return Optional.empty();
            return Optional.of(port);
        } catch (NumberFormatException e) {
            // Not exceptional — invalid input is expected from user data
            // Return empty rather than throwing; caller decides what to do
            return Optional.empty();
        }
    }

    // ----------------------------------------------------------------
    // Pattern 4: global boundary handler (Spring equivalent shown in comment)
    // For non-Spring apps: register at application startup
    // ----------------------------------------------------------------
    static void registerGlobalHandler() {
        Thread.setDefaultUncaughtExceptionHandler((thread, throwable) -> {
            log.severe("UNCAUGHT EXCEPTION in thread " + thread.getName()
                + ": " + throwable.getMessage());
            // In production: flush metrics, close resources, then allow JVM to exit
        });

        // Spring equivalent:
        // @ControllerAdvice
        // public class GlobalExceptionHandler {
        //     @ExceptionHandler(DataLayerException.class)
        //     public ResponseEntity<ErrorResponse> handleDataLayer(DataLayerException e) {
        //         log.error("Data layer failure", e);
        //         return ResponseEntity.status(503).body(new ErrorResponse(e.getMessage()));
        //     }
        // }
    }

    // ----------------------------------------------------------------
    // Placeholder for the injected DataSource — allows self-contained compilation
    // ----------------------------------------------------------------
    interface DataSource {
        Connection getConnection() throws SQLException;
    }

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

    public static void main(String[] args) {
        System.out.println("=== parsePort: Optional instead of exception ===");
        System.out.println(parsePort("8080"));    // Optional[8080]
        System.out.println(parsePort("not-a-port")); // Optional.empty
        System.out.println(parsePort("99999"));   // Optional.empty — out of range

        System.out.println("\n=== FastValidationException: no stack trace overhead ===");
        try {
            throw new FastValidationException("value out of range");
        } catch (FastValidationException e) {
            System.out.println("Caught: " + e.getMessage());
            System.out.println("Stack trace elements: " + e.getStackTrace().length); // 0
        }
    }
}