1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

// Java's Exception Hierarchy (Conceptual)
//
// Throwable
// ├── Error (unchecked - JVM/system problems)
// │   ├── OutOfMemoryError
// │   ├── StackOverflowError
// │   └── ...
// └── Exception
//     ├── RuntimeException (unchecked - programming errors)
//     │   ├── NullPointerException
//     │   ├── IllegalArgumentException
//     │   ├── IndexOutOfBoundsException
//     │   ├── IllegalStateException
//     │   └── ...
//     └── Other Exceptions (checked - recoverable conditions)
//         ├── IOException
//         ├── SQLException
//         └── ...
 
// UNCHECKED EXCEPTION: No declaration or handling required
public class Calculator {
    
    // Notice: No "throws" clause required
    public int divide(int a, int b) {
        if (b == 0) {
            // This is an unchecked exception - no declaration needed
            throw new ArithmeticException("Cannot divide by zero");
        }
        return a / b;
    }
    
    // Caller can choose to handle or not - compiler doesn't care
    public void performCalculation() {
        int result = divide(10, 0);  // Compiles fine!
        // But throws ArithmeticException at runtime
    }
    
    // Caller CAN handle if they want to
    public int safeDivide(int a, int b, int defaultValue) {
        try {
            return divide(a, b);
        } catch (ArithmeticException e) {
            return defaultValue;  // Voluntary handling
        }
    }
}
 
// Creating custom unchecked exceptions
public class OrderNotFoundException extends RuntimeException {
    
    private final String orderId;
    
    public OrderNotFoundException(String orderId) {
        super("Order not found: " + orderId);
        this.orderId = orderId;
    }
    
    public String getOrderId() {
        return orderId;
    }
}
 
// Using custom unchecked exceptions
public class OrderService {
    
    // No throws clause - unchecked exceptions don't need it
    public Order findOrder(String orderId) {
        Order order = repository.findById(orderId);
        if (order == null) {
            throw new OrderNotFoundException(orderId);
        }
        return order;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

// PRINCIPLE 1: Fail Fast for Programming Errors
// 
// Programming errors (bugs) should cause immediate, loud failure
// so developers discover and fix them during development
 
public class UserService {
    
    public User createUser(String email, String name) {
        // These are PRECONDITIONS - violations are bugs in calling code
        // Use unchecked exceptions because bugs aren't "recoverable" conditions
        
        if (email == null) {
            throw new NullPointerException("email cannot be null");
        }
        if (name == null) {
            throw new NullPointerException("name cannot be null");
        }
        if (!isValidEmail(email)) {
            throw new IllegalArgumentException("Invalid email format: " + email);
        }
        if (name.isBlank()) {
            throw new IllegalArgumentException("name cannot be blank");
        }
        
        // Actual logic proceeds only if preconditions are met
        return new User(email, name);
    }
}
 
 
// PRINCIPLE 2: Clean Interfaces
// 
// Compare these two interface designs:
 
// Cluttered with exception declarations
interface UserRepository_v1 {
    User findById(String id) 
        throws UserNotFoundException, DatabaseException, ConnectionException;
    
    List<User> findByRole(String role)
        throws DatabaseException, ConnectionException, InvalidRoleException;
    
    void save(User user)
        throws DatabaseException, ConnectionException, DuplicateUserException,
               ValidationException, ConstraintViolationException;
}
 
// Clean interface - exceptions documented but not declared
interface UserRepository {
    /**
     * Finds a user by ID.
     * 
     * @param id the user ID (must not be null)
     * @return the user
     * @throws UserNotFoundException if no user exists with this ID
     * @throws RepositoryException if a database error occurs
     */
    User findById(String id);
    
    List<User> findByRole(String role);
    
    void save(User user);
}
// Same information conveyed via documentation, cleaner code
 
 
// PRINCIPLE 3: Local Knowledge, Global Handling
//
// The code that detects an error often can't handle it appropriately
 
public class DeepBusinessLogic {
    
    public void processItem(Item item) {
        // This code knows HOW to detect the error...
        if (!item.isValid()) {
            throw new InvalidItemException(item);
        }
        
        // ...but it has NO IDEA about:
        // - Whether to retry
        // - How to notify the user
        // - Whether to log and continue, or abort everything
        // - What alternative action to take
        
        // So we throw, letting higher-level code decide
        doProcessing(item);
    }
}
 
public class RequestHandler {
    
    public Response handleRequest(Request request) {
        try {
            // Call deep business logic
            businessService.processRequest(request);
            return Response.success();
            
        } catch (InvalidItemException e) {
            // HERE we have context to handle appropriately
            logger.warn("Invalid item in request", e);
            return Response.badRequest(e.getMessage());
            
        } catch (ServiceUnavailableException e) {
            // Different handling for different exceptions
            logger.error("Downstream service unavailable", e);
            return Response.serviceUnavailable("Please retry later");
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// SCENARIO 1: Programming Errors
// These represent bugs, not runtime conditions
 
public class Validator {
    
    // Null parameters are programming errors - use unchecked exception
    public void validateUser(User user) {
        Objects.requireNonNull(user, "user cannot be null");
        Objects.requireNonNull(user.getEmail(), "email cannot be null");
        
        if (user.getAge() < 0) {
            throw new IllegalArgumentException(
                "age cannot be negative: " + user.getAge());
        }
    }
}
 
 
// SCENARIO 2: Violated Invariants
// When object state is corrupted, something is deeply wrong
 
public class BankAccount {
    private BigDecimal balance;
    
    public void withdraw(BigDecimal amount) {
        // Precondition check
        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Amount must be positive");
        }
        
        // Business rule check (might be recoverable in UI context)
        if (amount.compareTo(balance) > 0) {
            throw new InsufficientFundsException(balance, amount);
        }
        
        balance = balance.subtract(amount);
        
        // Invariant check - if this fails, we have a bug
        if (balance.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalStateException(
                "CRITICAL: Balance went negative after withdrawal - bug detected");
        }
    }
}
 
 
// SCENARIO 3: Deep Propagation
// Exception will travel through many layers
 
// Layer 4 (deepest): Data access
public class UserRepository {
    public User findById(String id) {
        User user = database.query("SELECT * FROM users WHERE id = ?", id);
        if (user == null) {
            throw new EntityNotFoundException("User", id);  // Unchecked
        }
        return user;
    }
}
 
// Layer 3: Domain service
public class UserService {
    public User getUser(String id) {
        return userRepository.findById(id);  // Just propagates
    }
}
 
// Layer 2: Application service
public class ProfileService {
    public UserProfile getProfile(String userId) {
        User user = userService.getUser(userId);  // Just propagates
        return buildProfile(user);
    }
}
 
// Layer 1: Controller (finally handles it)
public class ProfileController {
    public Response getProfile(String userId) {
        try {
            UserProfile profile = profileService.getProfile(userId);
            return Response.ok(profile);
        } catch (EntityNotFoundException e) {
            return Response.notFound(e.getMessage());
        }
    }
}
// With checked exceptions, ALL intermediate layers would need throws clauses
 
 
// SCENARIO 4: Functional Programming
// Lambdas work seamlessly with unchecked exceptions
 
public class DataProcessor {
    
    public List<User> processUsers(List<UserDTO> dtos) {
        return dtos.stream()
            .filter(dto -> dto.isActive())         // Can throw unchecked
            .map(dto -> convertToUser(dto))        // Can throw unchecked
            .filter(user -> validateUser(user))    // Can throw unchecked
            .collect(Collectors.toList());
    }
    
    // These can throw unchecked exceptions and lambdas work fine
    private User convertToUser(UserDTO dto) {
        if (dto.getEmail() == null) {
            throw new InvalidDataException("Email required");
        }
        return new User(dto.getEmail(), dto.getName());
    }
    
    private boolean validateUser(User user) {
        if (user.isFlagged()) {
            throw new SecurityException("User is flagged");
        }
        return true;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

public class ExceptionUsageGuide {
    
    // NULL POINTER / NULL REFERENCE
    // Use when a required non-null value is null
    public void processOrder(Order order) {
        // Option 1: Explicit check
        if (order == null) {
            throw new NullPointerException("order cannot be null");
        }
        
        // Option 2: Objects.requireNonNull (preferred)
        Objects.requireNonNull(order, "order cannot be null");
        
        // Option 3: Let it fail naturally (discouraged - message unclear)
        order.process();  // Throws NPE if order is null
    }
    
    
    // ILLEGAL ARGUMENT
    // Use when argument value is invalid (but not null)
    public void setAge(int age) {
        if (age < 0 || age > 150) {
            throw new IllegalArgumentException(
                "age must be between 0 and 150, got: " + age);
        }
        this.age = age;
    }
    
    public void setItems(List<Item> items) {
        if (items.isEmpty()) {
            throw new IllegalArgumentException("items cannot be empty");
        }
        this.items = new ArrayList<>(items);
    }
    
    
    // ILLEGAL STATE
    // Use when object is not in correct state for the operation
    public class Connection {
        private boolean connected = false;
        
        public void sendData(byte[] data) {
            if (!connected) {
                throw new IllegalStateException(
                    "Cannot send data before connecting");
            }
            doSend(data);
        }
        
        public void connect() {
            if (connected) {
                throw new IllegalStateException("Already connected");
            }
            doConnect();
            connected = true;
        }
    }
    
    
    // INDEX OUT OF BOUNDS
    // Use when index is outside valid range
    public class CircularBuffer<T> {
        private Object[] elements;
        private int size;
        
        public T get(int index) {
            if (index < 0 || index >= size) {
                throw new IndexOutOfBoundsException(
                    "Index: " + index + ", Size: " + size);
            }
            return (T) elements[wrapIndex(index)];
        }
    }
    
    
    // UNSUPPORTED OPERATION
    // Use when operation is not supported by this implementation
    public class ImmutableList<T> extends AbstractList<T> {
        private final T[] elements;
        
        @Override
        public boolean add(T element) {
            throw new UnsupportedOperationException(
                "Cannot add to immutable list");
        }
        
        @Override
        public T remove(int index) {
            throw new UnsupportedOperationException(
                "Cannot remove from immutable list");
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

// BASIC CUSTOM UNCHECKED EXCEPTION
// Extend RuntimeException for unchecked behavior
 
public class OrderProcessingException extends RuntimeException {
    
    public OrderProcessingException(String message) {
        super(message);
    }
    
    public OrderProcessingException(String message, Throwable cause) {
        super(message, cause);
    }
    
    public OrderProcessingException(Throwable cause) {
        super(cause);
    }
}
 
 
// RICH CUSTOM EXCEPTION WITH CONTEXT
// Include domain-specific information for better error handling
 
public class PaymentFailedException extends RuntimeException {
    
    private final String paymentId;
    private final BigDecimal amount;
    private final PaymentFailureReason reason;
    private final boolean retryable;
    
    public PaymentFailedException(
            String paymentId, 
            BigDecimal amount,
            PaymentFailureReason reason,
            boolean retryable) {
        super(buildMessage(paymentId, amount, reason));
        this.paymentId = paymentId;
        this.amount = amount;
        this.reason = reason;
        this.retryable = retryable;
    }
    
    public PaymentFailedException(
            String paymentId,
            BigDecimal amount,
            PaymentFailureReason reason,
            boolean retryable,
            Throwable cause) {
        super(buildMessage(paymentId, amount, reason), cause);
        this.paymentId = paymentId;
        this.amount = amount;
        this.reason = reason;
        this.retryable = retryable;
    }
    
    private static String buildMessage(
            String paymentId, BigDecimal amount, PaymentFailureReason reason) {
        return String.format(
            "Payment %s for amount %s failed: %s",
            paymentId, amount, reason);
    }
    
    // Rich getters for programmatic handling
    public String getPaymentId() { return paymentId; }
    public BigDecimal getAmount() { return amount; }
    public PaymentFailureReason getReason() { return reason; }
    public boolean isRetryable() { return retryable; }
}
 
public enum PaymentFailureReason {
    INSUFFICIENT_FUNDS,
    CARD_EXPIRED,
    FRAUD_DETECTED,
    GATEWAY_UNAVAILABLE,
    INVALID_CARD_NUMBER,
    DECLINED_BY_BANK
}
 
 
// EXCEPTION HIERARCHY FOR DOMAIN
// Create a hierarchy for related exceptions
 
public abstract class ECommerceException extends RuntimeException {
    protected ECommerceException(String message) {
        super(message);
    }
    protected ECommerceException(String message, Throwable cause) {
        super(message, cause);
    }
}
 
public class OrderException extends ECommerceException {
    private final String orderId;
    
    public OrderException(String orderId, String message) {
        super(message);
        this.orderId = orderId;
    }
    
    public String getOrderId() { return orderId; }
}
 
public class OrderNotFoundException extends OrderException {
    public OrderNotFoundException(String orderId) {
        super(orderId, "Order not found: " + orderId);
    }
}
 
public class OrderAlreadyCancelledException extends OrderException {
    public OrderAlreadyCancelledException(String orderId) {
        super(orderId, "Order already cancelled: " + orderId);
    }
}
 
public class OrderNotCancellableException extends OrderException {
    private final OrderStatus currentStatus;
    
    public OrderNotCancellableException(String orderId, OrderStatus currentStatus) {
        super(orderId, String.format(
            "Order %s cannot be cancelled in status %s", 
            orderId, currentStatus));
        this.currentStatus = currentStatus;
    }
    
    public OrderStatus getCurrentStatus() { return currentStatus; }
}
 
 
// USAGE: Handler can catch at different levels
public class OrderController {
    
    public Response cancelOrder(String orderId) {
        try {
            orderService.cancel(orderId);
            return Response.ok("Order cancelled");
            
        } catch (OrderNotFoundException e) {
            return Response.notFound(e.getMessage());
            
        } catch (OrderAlreadyCancelledException e) {
            // Idempotent - return success
            return Response.ok("Order was already cancelled");
            
        } catch (OrderNotCancellableException e) {
            return Response.badRequest(
                "Cannot cancel order in status: " + e.getCurrentStatus());
            
        } catch (OrderException e) {
            // Catch-all for any order-related exception
            logger.error("Unexpected order error", e);
            return Response.serverError("Order operation failed");
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

// PATTERN 1: Centralized Exception Handler
// Handle all exceptions at application boundaries
 
@ControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Logger logger = LoggerFactory.getLogger(
        GlobalExceptionHandler.class);
    
    // Handle specific domain exceptions
    @ExceptionHandler(OrderNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleOrderNotFound(
            OrderNotFoundException e, WebRequest request) {
        
        logger.info("Order not found: {}", e.getOrderId());
        return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(new ErrorResponse(
                "ORDER_NOT_FOUND",
                e.getMessage(),
                request.getDescription(false)
            ));
    }
    
    @ExceptionHandler(PaymentFailedException.class)
    public ResponseEntity<ErrorResponse> handlePaymentFailed(
            PaymentFailedException e, WebRequest request) {
        
        if (e.isRetryable()) {
            logger.warn("Retryable payment failure: {}", e.getPaymentId());
        } else {
            logger.error("Non-retryable payment failure", e);
        }
        
        return ResponseEntity
            .status(HttpStatus.PAYMENT_REQUIRED)
            .body(new ErrorResponse(
                e.getReason().name(),
                "Payment could not be processed",
                e.isRetryable() ? "Please try again" : "Please contact support"
            ));
    }
    
    // Catch-all for unexpected exceptions
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(
            Exception e, WebRequest request) {
        
        // Log unexpected exceptions with full stack trace
        logger.error("Unexpected error processing request", e);
        
        // Don't expose internal details to clients
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse(
                "INTERNAL_ERROR",
                "An unexpected error occurred",
                null
            ));
    }
}
 
 
// PATTERN 2: Exception Translation at Layer Boundaries
// Convert low-level exceptions to domain exceptions
 
public class UserRepositoryImpl implements UserRepository {
    
    private final JdbcTemplate jdbc;
    
    @Override
    public User findById(String id) {
        try {
            return jdbc.queryForObject(
                "SELECT * FROM users WHERE id = ?",
                userRowMapper,
                id
            );
        } catch (EmptyResultDataAccessException e) {
            // Translate to domain exception
            throw new UserNotFoundException(id);
        } catch (DataAccessException e) {
            // Translate infrastructure exception to domain exception
            throw new RepositoryException(
                "Failed to retrieve user: " + id, e);
        }
    }
}
 
 
// PATTERN 3: Exception-Safe Resource Handling
// Combine try-with-resources with exception handling
 
public class DocumentProcessor {
    
    public String processDocument(Path path) {
        try (InputStream input = Files.newInputStream(path);
             BufferedReader reader = new BufferedReader(
                 new InputStreamReader(input, StandardCharsets.UTF_8))) {
            
            return reader.lines()
                .map(this::processLine)
                .collect(Collectors.joining("\n"));
                
        } catch (FileNotFoundException e) {
            throw new DocumentNotFoundException(path.toString());
        } catch (IOException e) {
            throw new DocumentProcessingException(
                "Failed to process document: " + path, e);
        }
    }
}
 
 
// PATTERN 4: Defensive Catching with Fallback
// Catch exceptions and provide safe defaults
 
public class ConfigurationLoader {
    
    private static final int DEFAULT_TIMEOUT = 30;
    private static final int DEFAULT_MAX_RETRIES = 3;
    
    public Configuration loadWithDefaults(Path configPath) {
        Configuration config = new Configuration();
        
        try {
            Properties props = loadProperties(configPath);
            config.setTimeout(parseTimeout(props));
            config.setMaxRetries(parseMaxRetries(props));
        } catch (ConfigurationException e) {
            logger.warn("Failed to load configuration, using defaults", e);
            config.setTimeout(DEFAULT_TIMEOUT);
            config.setMaxRetries(DEFAULT_MAX_RETRIES);
        }
        
        return config;
    }
    
    private int parseTimeout(Properties props) {
        String value = props.getProperty("timeout");
        if (value == null) {
            return DEFAULT_TIMEOUT;
        }
        try {
            int timeout = Integer.parseInt(value);
            if (timeout <= 0) {
                throw new ConfigurationException(
                    "timeout must be positive: " + timeout);
            }
            return timeout;
        } catch (NumberFormatException e) {
            throw new ConfigurationException(
                "Invalid timeout value: " + value, e);
        }
    }
}