Java Try-Catch — Exception Handling, Custom Exceptions & Best Practices

java.lang.Throwable                    ← Root of everything throwable
├── java.lang.Error                    ← JVM-level problems — do NOT catch
│   ├── OutOfMemoryError               ← JVM ran out of heap memory
│   ├── StackOverflowError             ← Infinite recursion consumed call stack
│   ├── VirtualMachineError            ← Severe JVM internal error
│   ├── AssertionError                 ← assert statement failed
│   └── LinkageError                   ← Class loading / linking problem
│       └── NoClassDefFoundError       ← Class found at compile time but not runtime
│
└── java.lang.Exception               ← Application-level problems
    ├── java.lang.RuntimeException    ← UNCHECKED — compiler does not enforce
    │   ├── NullPointerException      ← Dereference of null reference
    │   ├── ArrayIndexOutOfBoundsException ← Array index out of range
    │   ├── ClassCastException        ← Invalid type cast
    │   ├── ArithmeticException       ← e.g., division by zero
    │   ├── IllegalArgumentException  ← Method received illegal argument
    │   ├── IllegalStateException     ← Method called at wrong time
    │   ├── NumberFormatException     ← Invalid string → number conversion
    │   ├── IndexOutOfBoundsException ← General index out of range
    │   │   └── StringIndexOutOfBoundsException
    │   ├── UnsupportedOperationException ← Operation not supported
    │   ├── ConcurrentModificationException ← Collection modified during iteration
    │   └── NoSuchElementException    ← Iterator has no more elements
    │
    ├── IOException                   ← CHECKED — I/O operation failed
    │   ├── FileNotFoundException     ← File does not exist
    │   └── SocketException           ← Network socket error
    ├── SQLException                  ← CHECKED — Database operation failed
    ├── ParseException                ← CHECKED — Parsing failed
    ├── CloneNotSupportedException    ← CHECKED — clone() not supported
    └── InterruptedException          ← CHECKED — Thread was interrupted

import java.io.*;
import java.sql.*;

public class CheckedVsUnchecked {

    // ✅ Checked — IOException must be caught or declared
    public String readFileContent(String path) throws IOException {
        // FileNotFoundException is a checked exception (subclass of IOException)
        // If we don't throw IOException, we MUST catch it here — compiler enforces this
        try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
            StringBuilder content = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                content.append(line).append("\n");
            }
            return content.toString();
        }
        // Removing 'throws IOException' without a try-catch → COMPILE ERROR
    }

    // ✅ Unchecked — IllegalArgumentException doesn't require declaration
    public double divide(double numerator, double denominator) {
        if (denominator == 0) {
            // No 'throws ArithmeticException' needed in signature
            throw new IllegalArgumentException(
                "Denominator cannot be zero — received: " + denominator);
        }
        return numerator / denominator;
    }

    // ✅ Both in the same method
    public void saveUserToDatabase(User user) throws SQLException {
        // Precondition check — unchecked (programming contract)
        if (user == null) {
            throw new IllegalArgumentException("User cannot be null");
        }
        if (user.getName() == null || user.getName().isBlank()) {
            throw new IllegalArgumentException("User name cannot be blank");
        }
        // Database failure — checked (external, recoverable)
        try (Connection conn = getConnection()) {
            PreparedStatement ps = conn.prepareStatement(
                "INSERT INTO users (name, email) VALUES (?, ?)");
            ps.setString(1, user.getName());
            ps.setString(2, user.getEmail());
            ps.executeUpdate();
        }
        // SQLException propagated to caller who can decide: retry, log, alert
    }

    private Connection getConnection() throws SQLException {
        return DriverManager.getConnection("jdbc:...", "user", "pass");
    }
}

public class TryCatchBasics {
    public static void main(String[] args) {

        // ✅ Basic try-catch
        try {
            int result = 10 / 0;            // Throws ArithmeticException
            System.out.println(result);     // ← NEVER reached
        } catch (ArithmeticException e) {
            System.out.println("Cannot divide by zero: " + e.getMessage());
        }
        System.out.println("Program continues..."); // ← Always reached

        // ✅ The exception object carries useful info
        try {
            String text = null;
            int length = text.length(); // Throws NullPointerException
        } catch (NullPointerException e) {
            System.out.println("Exception type:    " + e.getClass().getName());
            System.out.println("Message:           " + e.getMessage());
            System.out.println("Stack trace:");
            e.printStackTrace(); // Prints to System.err
        }

        // ✅ Catching a superclass catches all subclasses
        try {
            int[] arr = new int[3];
            arr[10] = 99; // Throws ArrayIndexOutOfBoundsException
        } catch (RuntimeException e) {
            // Catches ArrayIndexOutOfBoundsException and ALL RuntimeExceptions
            System.out.println("Caught: " + e.getClass().getSimpleName());
        }

        // ✅ When no exception is thrown — catch block is SKIPPED
        try {
            int result = 10 / 2;             // No exception
            System.out.println("Result: " + result); // 5 — this prints
        } catch (ArithmeticException e) {
            System.out.println("This never prints"); // Skipped
        }
        // Output: Result: 5

        // ✅ Exception object methods
        try {
            Integer.parseInt("not-a-number");
        } catch (NumberFormatException e) {
            System.out.println(e.getMessage());      // For input string: "not-a-number"
            System.out.println(e.getClass().getName()); // java.lang.NumberFormatException
            // e.getCause() — the causing exception (null if none)
            // e.getStackTrace() — StackTraceElement[]
            // e.toString() — class name + message
        }
    }
}

import java.io.*;

public class MultipleCatchBlocks {

    public void parseAndProcessFile(String filePath, String numberStr) {

        try {
            // Multiple potential failure points
            BufferedReader reader = new BufferedReader(new FileReader(filePath));
            String content = reader.readLine();
            int number = Integer.parseInt(numberStr);
            int result = 100 / number;
            System.out.println("Result: " + result);

        } catch (FileNotFoundException e) {
            // Most specific IOException subclass — must come BEFORE IOException
            System.err.println("File not found: " + filePath);
            System.err.println("Please check the file path and try again.");

        } catch (IOException e) {
            // General I/O failure — comes AFTER FileNotFoundException
            System.err.println("Failed to read file: " + e.getMessage());

        } catch (NumberFormatException e) {
            // Parsing failure
            System.err.println("'" + numberStr + "' is not a valid integer.");

        } catch (ArithmeticException e) {
            // Division by zero
            System.err.println("Cannot divide by zero. Provide a non-zero number.");

        } catch (Exception e) {
            // Catch-all — most general, MUST come last
            System.err.println("Unexpected error: " + e.getMessage());
            e.printStackTrace();
        }
    }

    // ❌ COMPILE ERROR — unreachable catch block
    public void wrongOrder() {
        try {
            new FileReader("file.txt");
        } catch (IOException e) {          // IOException is superclass of
            System.out.println("IO");
        } catch (FileNotFoundException e) { // ❌ COMPILE ERROR — already caught above!
            System.out.println("File");   // FileNotFoundException extends IOException
        }
    }
}

import java.io.*;
import java.sql.*;
import java.lang.reflect.*;

public class MultiCatch {

    public void processData(String input) {

        // ❌ BEFORE Java 7 — repetitive catch blocks with identical handling
        try {
            // ... code ...
        } catch (IOException e) {
            logError(e);
            notifyAdmin(e);
        } catch (SQLException e) {
            logError(e);   // Exact same code — copy-paste
            notifyAdmin(e);
        } catch (ParseException e) {
            logError(e);   // Exact same code — copy-paste
            notifyAdmin(e);
        }

        // ✅ Java 7+ — multi-catch with | operator
        try {
            performOperation(input);
        } catch (IOException | SQLException | ParseException e) {
            // 'e' is effectively final here — cannot be reassigned
            logError(e);
            notifyAdmin(e);
        }

        // ✅ Multi-catch with different handling for different groups
        try {
            riskyOperation(input);
        } catch (NullPointerException | IllegalArgumentException e) {
            // Input validation failures — client error
            System.err.println("Invalid input: " + e.getMessage());
            throw new BadRequestException("Invalid request data", e);
        } catch (IOException | SQLException e) {
            // Infrastructure failures — server error
            System.err.println("Infrastructure failure: " + e.getMessage());
            throw new ServiceUnavailableException("Service temporarily unavailable", e);
        }
    }

    // ❌ Multi-catch does NOT allow superclass and subclass together
    public void invalidMultiCatch() {
        try {
            new FileReader("x");
        } catch (IOException | FileNotFoundException e) { // ❌ COMPILE ERROR
            // FileNotFoundException is a subclass of IOException —
            // they cannot appear together in multi-catch (redundant)
        }
    }

    private void performOperation(String s) throws IOException, SQLException, ParseException {}
    private void riskyOperation(String s) throws IOException, SQLException {}
    private void logError(Throwable t) {}
    private void notifyAdmin(Throwable t) {}
}

import java.io.*;

public class FinallyBlock {

    // ✅ Classic use case: resource cleanup before try-with-resources
    public String readFileLegacy(String path) throws IOException {
        BufferedReader reader = null;
        try {
            reader = new BufferedReader(new FileReader(path));
            return reader.readLine();
        } catch (FileNotFoundException e) {
            System.err.println("File not found: " + path);
            return null;
        } finally {
            // ✅ Always runs — whether exception was thrown or not
            if (reader != null) {
                try {
                    reader.close();
                } catch (IOException e) {
                    System.err.println("Failed to close reader: " + e.getMessage());
                }
            }
            System.out.println("Cleanup complete."); // Always prints
        }
    }

    // ✅ finally with return — TRICKY behaviour
    public int trickyReturn() {
        try {
            System.out.println("Try block");
            return 1;             // ← Starts to return 1...
        } finally {
            System.out.println("Finally block"); // ← ...but this runs first
            return 2;             // ← Return in finally OVERRIDES return in try!
        }
        // Output: Try block → Finally block
        // Actual return value: 2  ← finally wins
    }

    // ✅ finally with exception — also tricky
    public void trickyException() throws Exception {
        try {
            throw new IOException("From try");
        } finally {
            throw new RuntimeException("From finally"); // ← Suppresses IOException!
        }
        // Only RuntimeException propagates — IOException is SILENTLY LOST
        // This is why throwing from finally is an anti-pattern
    }

    // ✅ finally without catch — try-finally (no catch needed)
    public void updateWithLock(ReentrantLock lock) {
        lock.lock();
        try {
            performUpdate(); // If this throws, lock still gets released
        } finally {
            lock.unlock(); // ALWAYS releases the lock
        }
    }

    // ❌ When does finally NOT run? Only in these rare cases:
    public void whenFinallySkips() {
        try {
            System.exit(0); // ← JVM terminates — finally DOES NOT run
        } finally {
            System.out.println("This never prints when System.exit() is called");
        }
    }

    private void performUpdate() {}
    static class ReentrantLock {
        void lock() {}
        void unlock() {}
    }
}

import java.io.*;
import java.sql.*;

public class TryWithResources {

    // ✅ Single resource — simplest form
    public String readFirstLine(String path) throws IOException {
        try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
            return reader.readLine();
            // reader.close() is called automatically here — always
        }
        // Compare: no finally block needed at all
    }

    // ✅ Multiple resources — closed in REVERSE order of declaration
    public void copyFile(String sourcePath, String destPath) throws IOException {
        try (FileInputStream  fis  = new FileInputStream(sourcePath);   // opened 1st
             FileOutputStream fos  = new FileOutputStream(destPath);    // opened 2nd
             BufferedInputStream  in  = new BufferedInputStream(fis);   // opened 3rd
             BufferedOutputStream out = new BufferedOutputStream(fos)) {// opened 4th

            byte[] buffer = new byte[8192];
            int bytesRead;
            while ((bytesRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, bytesRead);
            }
            // Close order: out → in → fos → fis  (reverse of opening)
        }
    }

    // ✅ JDBC — try-with-resources for connections, statements, result sets
    public User findUserById(Connection conn, long userId) throws SQLException {
        String sql = "SELECT id, name, email FROM users WHERE id = ?";

        try (PreparedStatement ps   = conn.prepareStatement(sql);
             // Note: Connection is NOT declared here — it's passed in and
             // managed by the connection pool, not closed here
             ) {

            ps.setLong(1, userId);

            try (ResultSet rs = ps.executeQuery()) {
                if (rs.next()) {
                    return new User(rs.getLong("id"), rs.getString("name"),
                                   rs.getString("email"));
                }
                return null;
            }
            // rs.close() called automatically
        }
        // ps.close() called automatically
    }

    // ✅ Java 9+: Effectively-final variables in try header (no redeclaration)
    public void java9Style() throws IOException {
        BufferedReader reader = new BufferedReader(new FileReader("data.txt"));
        // In Java 9+, effectively-final variables can be used directly:
        try (reader) {            // No need to redeclare — Java 9+
            System.out.println(reader.readLine());
        }
    }

    // ✅ Custom AutoCloseable — any class can participate
    static class DatabaseTransaction implements AutoCloseable {
        private final Connection connection;
        private boolean committed = false;

        DatabaseTransaction(Connection connection) throws SQLException {
            this.connection = connection;
            this.connection.setAutoCommit(false);
            System.out.println("Transaction started");
        }

        public void commit() throws SQLException {
            connection.commit();
            committed = true;
        }

        @Override
        public void close() throws SQLException {
            if (!committed) {
                System.out.println("Auto-rolling back transaction");
                connection.rollback(); // Rollback if not committed
            }
            connection.setAutoCommit(true);
        }
    }

    public void transferFunds(Connection conn, long fromId,
                              long toId, double amount) throws SQLException {
        try (DatabaseTransaction tx = new DatabaseTransaction(conn)) {
            deductBalance(conn, fromId, amount);
            addBalance(conn, toId, amount);
            tx.commit(); // Only commits if both succeed
            // If exception occurs before commit → auto-rollback via close()
        }
    }

    private void deductBalance(Connection c, long id, double amt) throws SQLException {}
    private void addBalance(Connection c, long id, double amt) throws SQLException {}
    private static class User {
        User(long id, String name, String email) {}
    }
}

public class ThrowKeyword {

    // ✅ Throwing unchecked — precondition validation (guard clause pattern)
    public void setAge(int age) {
        if (age < 0 || age > 150) {
            throw new IllegalArgumentException(
                "Age must be between 0 and 150. Received: " + age);
        }
        this.age = age;
    }

    // ✅ Throwing unchecked — null check (prefer Objects.requireNonNull)
    public void processOrder(Order order) {
        if (order == null) {
            throw new NullPointerException("order must not be null");
        }
        // ✅ Better idiom (Java 7+):
        java.util.Objects.requireNonNull(order, "order must not be null");
        java.util.Objects.requireNonNull(order.getId(), "order ID must not be null");
    }

    // ✅ Throwing checked — callers must handle or declare
    public byte[] readBytes(String path) throws IOException {
        java.io.File file = new java.io.File(path);
        if (!file.exists()) {
            throw new java.io.FileNotFoundException(
                "File not found at path: " + path);
        }
        if (!file.canRead()) {
            throw new java.io.IOException(
                "No read permission for file: " + path);
        }
        return java.nio.file.Files.readAllBytes(file.toPath());
    }

    // ✅ Re-throwing — catch, do something, rethrow same exception
    public void processWithLogging(String data) throws IOException {
        try {
            riskyOperation(data);
        } catch (IOException e) {
            System.err.println("Failed to process: " + data); // Log
            throw e; // Rethrow — caller still handles it
        }
    }

    // ✅ Wrapping — catch one type, throw another with more context
    public User loadUser(String userId) {
        try {
            return userRepository.findById(userId);
        } catch (SQLException e) {
            // Translate infrastructure exception to domain exception
            throw new UserServiceException(
                "Failed to load user with ID: " + userId, e); // 'e' becomes the cause
        }
    }

    // ✅ throw in a conditional chain — useful for state machines
    public void cancelOrder(Order order) {
        if (order.getStatus() == OrderStatus.DELIVERED) {
            throw new IllegalStateException(
                "Cannot cancel order " + order.getId() + " — already delivered.");
        }
        if (order.getStatus() == OrderStatus.CANCELLED) {
            throw new IllegalStateException(
                "Order " + order.getId() + " is already cancelled.");
        }
        order.setStatus(OrderStatus.CANCELLED);
    }

    private int age;
    private Object userRepository;
    private void riskyOperation(String s) throws IOException {}
    private static class Order {
        Object getId() { return null; }
        OrderStatus getStatus() { return null; }
        void setStatus(OrderStatus s) {}
    }
    private enum OrderStatus { DELIVERED, CANCELLED }
}

import java.io.*;
import java.sql.*;

public class ThrowsKeyword {

    // ✅ Declaring a single checked exception
    public String readFile(String path) throws IOException {
        return new String(java.nio.file.Files.readAllBytes(
            java.nio.file.Paths.get(path)));
    }

    // ✅ Declaring multiple checked exceptions
    public User authenticateAndLoad(String token) throws IOException, SQLException {
        String userId = validateToken(token);    // throws IOException
        return loadFromDatabase(userId);         // throws SQLException
    }

    // ✅ Propagating up a chain of methods
    // Level 3 — throws declared
    private String validateToken(String token) throws IOException {
        // Calls a method that throws IOException
        return readFile("/tokens/" + token);
    }

    // Level 2 — propagates declared exception
    private User loadFromDatabase(String userId) throws SQLException {
        Connection conn = DriverManager.getConnection("jdbc:...");
        // ...query...
        return null;
    }

    // ✅ throws in interface / abstract class — callers of ALL implementations must handle
    interface DataRepository {
        User findById(long id) throws SQLException;
        void save(User user) throws SQLException;
    }

    // ✅ Overriding: subclass can declare FEWER exceptions, not more
    static class BaseService {
        public void execute() throws IOException, SQLException { }
    }

    static class ConcreteService extends BaseService {
        @Override
        public void execute() throws IOException { } // ✅ Removed SQLException — allowed
        // throws IOException, SQLException, RuntimeException — ✅ can add unchecked
        // throws IOException, SQLException, Exception — ❌ COMPILE ERROR: broader checked
    }

    // ✅ Documenting unchecked exceptions in throws (optional but professional)
    /**
     * @throws IllegalArgumentException if amount is negative or zero
     * @throws InsufficientFundsException if account balance is insufficient
     */
    public void withdraw(double amount) throws InsufficientFundsException {
        if (amount <= 0) {
            throw new IllegalArgumentException("Withdrawal amount must be positive");
        }
        if (this.balance < amount) {
            throw new InsufficientFundsException(this.balance, amount);
        }
        this.balance -= amount;
    }

    private double balance = 5000;
    private static class User {}
    private static class InsufficientFundsException extends RuntimeException {
        InsufficientFundsException(double balance, double amount) {
            super(String.format("Insufficient funds. Balance: %.2f, Requested: %.2f",
                balance, amount));
        }
    }
}

// ✅ Base domain exception — all app exceptions extend this
public class AppException extends RuntimeException {
    private final String errorCode;

    public AppException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }
    public AppException(String errorCode, String message, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }
    public String getErrorCode() { return errorCode; }
}

// ✅ Domain-specific: carries failure context as typed fields
public class InsufficientFundsException extends AppException {

    private final double availableBalance;
    private final double requestedAmount;
    private final String accountId;

    public InsufficientFundsException(String accountId,
                                       double availableBalance,
                                       double requestedAmount) {
        super("INSUFFICIENT_FUNDS",
            String.format("Account %s has insufficient funds. " +
                "Available: %.2f, Requested: %.2f",
                accountId, availableBalance, requestedAmount));
        this.accountId        = accountId;
        this.availableBalance = availableBalance;
        this.requestedAmount  = requestedAmount;
    }

    public double getAvailableBalance() { return availableBalance; }
    public double getRequestedAmount()  { return requestedAmount; }
    public String getAccountId()         { return accountId; }
    public double getDeficit()           { return requestedAmount - availableBalance; }
}

// ✅ Resource-not-found exception — generic, parameterised
public class ResourceNotFoundException extends AppException {

    private final String resourceType;
    private final Object resourceId;

    public ResourceNotFoundException(String resourceType, Object resourceId) {
        super("RESOURCE_NOT_FOUND",
            resourceType + " not found with ID: " + resourceId);
        this.resourceType = resourceType;
        this.resourceId   = resourceId;
    }

    // Convenient static factories
    public static ResourceNotFoundException forUser(long userId) {
        return new ResourceNotFoundException("User", userId);
    }
    public static ResourceNotFoundException forOrder(String orderId) {
        return new ResourceNotFoundException("Order", orderId);
    }

    public String getResourceType() { return resourceType; }
    public Object getResourceId()   { return resourceId; }
}

// ✅ Checked exception — external API call failed
public class PaymentGatewayException extends Exception {

    private final int    gatewayErrorCode;
    private final String transactionId;
    private final boolean retryable;

    public PaymentGatewayException(int gatewayErrorCode, String transactionId,
                                   boolean retryable, String message) {
        super(message);
        this.gatewayErrorCode = gatewayErrorCode;
        this.transactionId    = transactionId;
        this.retryable        = retryable;
    }
    public PaymentGatewayException(int code, String txId,
                                   boolean retryable, String msg, Throwable cause) {
        super(msg, cause);
        this.gatewayErrorCode = code;
        this.transactionId    = txId;
        this.retryable        = retryable;
    }

    public int    getGatewayErrorCode() { return gatewayErrorCode; }
    public String getTransactionId()    { return transactionId; }
    public boolean isRetryable()        { return retryable; }
}

public class ExceptionChaining {

    // ❌ BAD: Losing the original cause — debugging becomes impossible
    public User findUserBad(long id) {
        try {
            return userDao.findById(id);
        } catch (SQLException e) {
            // e is swallowed — DBA can never find out what SQL failed
            throw new RuntimeException("Failed to find user");
        }
    }

    // ❌ ALSO BAD: Logging AND rethrowing — the exception gets logged twice
    public User findUserAlsoBad(long id) {
        try {
            return userDao.findById(id);
        } catch (SQLException e) {
            log.error("DB error", e);      // Logged here
            throw new RuntimeException(e);  // AND rethrown — logged again by caller
        }
    }

    // ✅ GOOD: Wrap with cause — original stack trace fully preserved
    public User findUser(long userId) {
        try {
            return userDao.findById(userId);
        } catch (SQLException e) {
            // 'e' becomes the cause — full chain preserved in stack trace
            throw new UserServiceException(
                "Failed to retrieve user with ID: " + userId, e);
        }
    }

    // ✅ Reading the chain — traversing causes programmatically
    public static void printExceptionChain(Throwable t) {
        System.out.println("Exception chain:");
        int level = 0;
        Throwable current = t;
        while (current != null) {
            System.out.println("  ".repeat(level) +
                "[" + level + "] " + current.getClass().getSimpleName() +
                ": " + current.getMessage());
            current = current.getCause();
            level++;
        }
    }

    // ✅ Full chain visible in stack trace output:
    // com.app.UserServiceException: Failed to retrieve user with ID: 42
    //     at com.app.UserService.findUser(UserService.java:35)
    //     ...
    // Caused by: java.sql.SQLException: Connection refused to host: db.example.com
    //     at com.mysql.jdbc.Driver.connect(Driver.java:...)
    //     ...
    // Caused by: java.net.ConnectException: Connection refused
    //     at java.net.Socket.connect(Socket.java:...)

    // ✅ Useful cause-inspection utility
    public static boolean hasCause(Throwable t, Class<? extends Throwable> type) {
        Throwable current = t;
        while (current != null) {
            if (type.isInstance(current)) return true;
            current = current.getCause();
        }
        return false;
    }

    private Object userDao;
    private Object log;
    private static class UserServiceException extends RuntimeException {
        UserServiceException(String msg, Throwable cause) { super(msg, cause); }
    }
}

public class ExceptionVsError {

    // ❌ DANGEROUS: Catching Error — looks safe, is a lie
    public void dangerousCatch() {
        try {
            processHugeDataSet();
        } catch (OutOfMemoryError e) {
            System.out.println("Caught OOM — continuing..."); // FALSE SAFETY
            // Reality: heap is still full, next allocation will fail again
            // JVM may be in corrupt state — undefined behaviour ahead
        }
    }

    // ❌ ALSO DANGEROUS: Catching Throwable in business code
    public void catchThrowable() {
        try {
            businessLogic();
        } catch (Throwable t) { // Catches Error too — almost always wrong
            log(t);
        }
    }

    // ✅ The ONE legitimate use: graceful shutdown handler at app boundary
    public static void main(String[] args) {
        try {
            Application.start();
        } catch (Throwable t) {
            // Top-level catch at JVM entry point — only acceptable location
            System.err.println("FATAL: Application crashed: " + t.getMessage());
            t.printStackTrace();
            System.exit(1); // Explicit exit with error code
        }
    }

    // ✅ StackOverflowError — caused by unguarded recursion
    public int factorial(int n) {
        // ❌ No base case — will throw StackOverflowError
        return n * factorial(n - 1);
    }

    public int factorialSafe(int n) {
        if (n < 0)  throw new IllegalArgumentException("n must be non-negative");
        if (n == 0) return 1; // ✅ Base case prevents StackOverflowError
        return n * factorialSafe(n - 1);
    }

    private void processHugeDataSet() {}
    private void businessLogic() {}
    private void log(Throwable t) {}
    private static class Application { static void start() {} }
}

// ❌ ANTI-PATTERN 1: Swallowing — the silent killer
try {
    saveOrderToDatabase(order);
} catch (Exception e) {
    // NOTHING HERE — order silently not saved, user thinks it was
}

// ✅ BETTER: At minimum, log. Ideally rethrow or return failure signal.
try {
    saveOrderToDatabase(order);
} catch (SQLException e) {
    log.error("Failed to save order {}: {}", order.getId(), e.getMessage(), e);
    throw new OrderPersistenceException("Could not save order " + order.getId(), e);
}

// ❌ ANTI-PATTERN 2: Exception as flow control — slow and misleading
public User findUser(String id) {
    try {
        return userCache.get(id); // Throws if not found
    } catch (CacheException e) {
        return null; // Using exception to signal 'not found' — wrong
    }
}

// ✅ BETTER: Check, don't catch
public Optional<User> findUser(String id) {
    if (userCache.contains(id)) {
        return Optional.of(userCache.get(id));
    }
    return Optional.empty(); // Explicit 'not found' without exception
}

// ❌ ANTI-PATTERN 3: Returning null from catch
public Config loadConfig(String path) {
    try {
        return parseConfigFile(path);
    } catch (IOException e) {
        return null; // Caller has no idea WHY it's null
    }
}

// ✅ BETTER: Throw with context or return Optional
public Config loadConfig(String path) {
    try {
        return parseConfigFile(path);
    } catch (IOException e) {
        throw new ConfigurationException(
            "Cannot load config from: " + path, e);
    }
}

package com.techsustainify.api.exception;

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import java.time.Instant;
import java.util.*;

/**
 * Centralised exception handler for all REST controllers.
 * Translates domain exceptions into HTTP responses.
 * Logs once — no other layer logs these exceptions.
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final org.slf4j.Logger log =
        org.slf4j.LoggerFactory.getLogger(GlobalExceptionHandler.class);

    // ✅ Domain: Resource not found → 404
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        log.warn("Resource not found: {} with ID {}",
            ex.getResourceType(), ex.getResourceId());
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(ErrorResponse.of("RESOURCE_NOT_FOUND", ex.getMessage()));
    }

    // ✅ Domain: Insufficient funds → 422 Unprocessable Entity
    @ExceptionHandler(InsufficientFundsException.class)
    public ResponseEntity<ErrorResponse> handleInsufficientFunds(
            InsufficientFundsException ex) {
        log.info("Insufficient funds for account {}: balance={}, requested={}",
            ex.getAccountId(), ex.getAvailableBalance(), ex.getRequestedAmount());
        Map<String, Object> details = new LinkedHashMap<>();
        details.put("availableBalance", ex.getAvailableBalance());
        details.put("requestedAmount",  ex.getRequestedAmount());
        details.put("deficit",          ex.getDeficit());
        return ResponseEntity
            .status(HttpStatus.UNPROCESSABLE_ENTITY)
            .body(ErrorResponse.of("INSUFFICIENT_FUNDS", ex.getMessage(), details));
    }

    // ✅ Validation: Bad request input → 400
    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ErrorResponse> handleBadRequest(IllegalArgumentException ex) {
        log.debug("Bad request: {}", ex.getMessage());
        return ResponseEntity
            .status(HttpStatus.BAD_REQUEST)
            .body(ErrorResponse.of("INVALID_REQUEST", ex.getMessage()));
    }

    // ✅ External: Payment gateway failure
    @ExceptionHandler(PaymentGatewayException.class)
    public ResponseEntity<ErrorResponse> handlePaymentGateway(
            PaymentGatewayException ex) {
        log.error("Payment gateway error: code={}, txId={}, retryable={}",
            ex.getGatewayErrorCode(), ex.getTransactionId(), ex.isRetryable(), ex);
        HttpStatus status = ex.isRetryable()
            ? HttpStatus.SERVICE_UNAVAILABLE
            : HttpStatus.BAD_GATEWAY;
        return ResponseEntity.status(status)
            .body(ErrorResponse.of("PAYMENT_FAILED", ex.getMessage()));
    }

    // ✅ Catch-all: Unexpected server errors → 500
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
        log.error("Unexpected error — this should be investigated", ex);
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(ErrorResponse.of("INTERNAL_ERROR",
                "An unexpected error occurred. Please try again."));
    }

    // Standard error response body
    public record ErrorResponse(
        String    errorCode,
        String    message,
        Instant   timestamp,
        Map<String, Object> details
    ) {
        static ErrorResponse of(String code, String message) {
            return new ErrorResponse(code, message, Instant.now(), Map.of());
        }
        static ErrorResponse of(String code, String message,
                                Map<String, Object> details) {
            return new ErrorResponse(code, message, Instant.now(), details);
        }
    }
}

package com.techsustainify.payment.service;

import java.util.Objects;

public class PaymentService {

    private final AccountRepository accountRepo;
    private final PaymentGatewayClient gatewayClient;
    private final TransactionRepository txRepo;

    /**
     * Processes a payment with full exception handling:
     * - Precondition validation (unchecked)
     * - Business rule enforcement (domain exception)
     * - Infrastructure failure translation (exception wrapping)
     * - Resource management (try-with-resources)
     *
     * @throws IllegalArgumentException  if request is invalid (programming error)
     * @throws ResourceNotFoundException if account not found (domain error)
     * @throws InsufficientFundsException if balance too low (domain error)
     * @throws PaymentGatewayException   if external gateway fails (infrastructure)
     */
    public TransactionResult processPayment(PaymentRequest request) {

        // ✅ Precondition checks — fast fail with clear messages
        Objects.requireNonNull(request, "PaymentRequest must not be null");
        Objects.requireNonNull(request.getAccountId(), "Account ID required");
        if (request.getAmount() <= 0) {
            throw new IllegalArgumentException(
                "Payment amount must be positive. Received: " + request.getAmount());
        }

        // ✅ Load resource — throws domain exception if not found
        Account account = accountRepo.findById(request.getAccountId())
            .orElseThrow(() -> ResourceNotFoundException.forAccount(
                request.getAccountId()));

        // ✅ Business rule — throws domain exception with context
        if (account.getBalance() < request.getAmount()) {
            throw new InsufficientFundsException(
                account.getId(),
                account.getBalance(),
                request.getAmount()
            );
        }

        // ✅ Infrastructure call — wrap checked exceptions in domain exception
        GatewayResponse gatewayResponse;
        try {
            gatewayResponse = gatewayClient.charge(
                account.getPaymentToken(),
                request.getAmount(),
                request.getCurrency()
            );
        } catch (GatewayTimeoutException e) {
            throw new PaymentGatewayException(
                e.getCode(), request.getIdempotencyKey(),
                true, // retryable — timeout may be transient
                "Payment gateway timed out", e);
        } catch (GatewayRejectionException e) {
            throw new PaymentGatewayException(
                e.getCode(), request.getIdempotencyKey(),
                false, // not retryable — card rejected
                "Payment rejected by gateway: " + e.getReason(), e);
        }

        // ✅ Persist transaction — catch and wrap SQL exception
        try {
            Transaction tx = Transaction.builder()
                .accountId(account.getId())
                .amount(request.getAmount())
                .gatewayRef(gatewayResponse.getTransactionId())
                .build();
            txRepo.save(tx);
            account.deductBalance(request.getAmount());
            accountRepo.save(account);
            return TransactionResult.success(tx.getId(), gatewayResponse);
        } catch (Exception e) {
            // Gateway charged but DB failed — log for manual reconciliation
            log.error("CRITICAL: Payment charged by gateway ({}) but not persisted!",
                gatewayResponse.getTransactionId(), e);
            throw new PaymentReconciliationException(
                gatewayResponse.getTransactionId(),
                "Payment processed externally but internal record failed", e);
        }
    }
}