Checked vs Unchecked Exceptions

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
157
158
159
160
161
162
163

/*
 * THE EXCEPTION TYPE DECISION TREE
 * 
 * Start here for every exception you consider throwing:
 * 
 * 1. Is this a PROGRAMMING ERROR?
 *    └── YES → UNCHECKED EXCEPTION (IllegalArgumentException, NullPointerException, etc.)
 *    └── NO  → Continue to #2
 * 
 * 2. Is this UNRECOVERABLE at any level?
 *    └── YES → UNCHECKED EXCEPTION (SystemFailureException, ConfigurationException)
 *    └── NO  → Continue to #3
 * 
 * 3. Can the IMMEDIATE CALLER recover?
 *    └── NO  → Continue to #4
 *    └── YES → Continue to #5
 * 
 * 4. Will this exception PROPAGATE through many layers?
 *    └── YES → UNCHECKED EXCEPTION (cleaner intermediate code)
 *    └── NO  → Continue to #5
 * 
 * 5. Is the exception part of a PUBLIC API that needs stability?
 *    └── YES → Consider impact of API evolution, then continue
 *    └── NO  → Continue to #6
 * 
 * 6. Are the BENEFITS of compile-time checking worth the COSTS?
 *    Consider:
 *    - Signature pollution through call chain
 *    - Risk of swallowed exceptions if too burdensome
 *    - Documentation alternatives
 *    - Team conventions and preferences
 *    
 *    └── YES → CHECKED EXCEPTION
 *    └── NO  → UNCHECKED EXCEPTION
 */
 
// EXAMPLE APPLICATIONS OF THE FRAMEWORK
 
public class ExampleDecisions {
    
    // ============================================
    // DECISION: UNCHECKED - Programming Error
    // ============================================
    
    /**
     * Null parameter is a caller bug, not a runtime condition.
     * Use unchecked exception - caller needs to fix their code,
     * not "handle" the null.
     */
    public void processOrder(Order order) {
        Objects.requireNonNull(order, "order cannot be null");
        // ... process
    }
    
    /**
     * Negative quantity is a caller bug.
     * Invalid arguments indicate programming errors.
     */
    public void setQuantity(int quantity) {
        if (quantity < 0) {
            throw new IllegalArgumentException(
                "quantity cannot be negative: " + quantity);
        }
        this.quantity = quantity;
    }
    
    
    // ============================================
    // DECISION: UNCHECKED - Unrecoverable
    // ============================================
    
    /**
     * If the database is down at startup, the application
     * simply cannot run. No recovery is possible.
     */
    public DataSource initializeDatabase() {
        try {
            return createDataSource();
        } catch (SQLException e) {
            throw new FatalStartupException(
                "Cannot connect to database - application cannot start", e);
        }
    }
    
    
    // ============================================
    // DECISION: UNCHECKED - Deep Propagation
    // ============================================
    
    /**
     * Entity not found typically propagates through many layers:
     * Repository → Service → Facade → Controller
     * 
     * Only the controller (boundary) can respond meaningfully
     * (return 404). Intermediate layers just propagate.
     */
    public Order findOrder(String orderId) {
        Order order = repository.findById(orderId);
        if (order == null) {
            throw new OrderNotFoundException(orderId);  // Unchecked
        }
        return order;
    }
    
    
    // ============================================
    // DECISION: CHECKED - Immediate Recovery Expected
    // ============================================
    
    /**
     * User input validation errors are EXPECTED (users make mistakes)
     * and the immediate caller CAN recover (show error, ask again).
     * 
     * This is a case where checked exception makes sense.
     */
    public LocalDate parseUserDate(String input) 
            throws InvalidDateFormatException {  // Checked
        try {
            return LocalDate.parse(input, formatter);
        } catch (DateTimeParseException e) {
            throw new InvalidDateFormatException(
                "Expected format: YYYY-MM-DD", e);
        }
    }
    
    // Caller handles immediately
    public void handleDateInput(String input) {
        try {
            this.date = parseUserDate(input);
            moveToNextField();
        } catch (InvalidDateFormatException e) {
            showValidationError(e.getMessage());  // Meaningful recovery
        }
    }
    
    
    // ============================================
    // DECISION: CHECKED - Safety-Critical Context
    // ============================================
    
    /**
     * Financial transactions require careful error handling.
     * Missing a failure here can result in incorrect balances.
     * The cost of compile-time checking is worth the safety.
     */
    public TransferReceipt transfer(Account from, Account to, Money amount)
            throws InsufficientFundsException, 
                   TransferLimitExceededException,
                   AccountFrozenException {  // All checked
        
        validateTransfer(from, to, amount);
        
        try {
            from.debit(amount);
            to.credit(amount);
            return createReceipt(from, to, amount);
        } catch (AccountException e) {
            // Rollback required - mustn't be missed
            reverseDebit(from, amount);
            throw e;
        }
    }
}

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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214

// ===================================================
// SCENARIO: Entity/Resource Not Found
// RECOMMENDATION: Unchecked (usually)
// ===================================================
 
// RATIONALE:
// - Typically propagates to controller/boundary layer
// - Intermediate service layers can't do anything meaningful
// - Entity absence is often a normal part of operations
 
public class OrderService {
    
    // Preferred: Unchecked exception
    public Order getOrder(String orderId) {
        return orderRepository.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException(orderId));
    }
    
    // Alternative: Return Optional (no exception)
    public Optional<Order> findOrder(String orderId) {
        return orderRepository.findById(orderId);
    }
}
 
// Exception handled at boundary
@RestController
public class OrderController {
    
    @GetMapping("/orders/{id}")
    public ResponseEntity<Order> getOrder(@PathVariable String id) {
        try {
            return ResponseEntity.ok(orderService.getOrder(id));
        } catch (OrderNotFoundException e) {
            return ResponseEntity.notFound().build();
        }
    }
}
 
 
// ===================================================
// SCENARIO: External Service/API Failures
// RECOMMENDATION: Unchecked (usually)
// ===================================================
 
// RATIONALE:
// - Callers typically can't retry (circuit breaker should)
// - Failure handling is centralized (exception handler)
// - Many layers between call site and meaningful handler
 
public class PaymentGatewayClient {
    
    // Unchecked - callers typically can't recover
    public PaymentResult charge(PaymentRequest request) {
        try {
            HttpResponse response = httpClient.post(
                gatewayUrl, 
                serialize(request)
            );
            return parseResponse(response);
        } catch (IOException e) {
            throw new PaymentGatewayException(
                "Failed to reach payment gateway", e);
        }
    }
}
 
 
// ===================================================
// SCENARIO: User Input Validation
// RECOMMENDATION: Can go either way - depends on context
// ===================================================
 
// OPTION A: Checked exception - immediate caller handles
// Good when: UI/form context, caller will show validation message
 
public class UserInputValidator {
    
    /**
     * @throws ValidationException caller shows error to user
     */
    public Email parseEmail(String input) throws ValidationException {
        if (!EMAIL_PATTERN.matcher(input).matches()) {
            throw new ValidationException("Invalid email format");
        }
        return new Email(input);
    }
}
 
// Immediate caller handles
public class RegistrationForm {
    public void onEmailEntered(String email) {
        try {
            this.email = validator.parseEmail(email);
        } catch (ValidationException e) {
            showFieldError("email", e.getMessage());  // Meaningful recovery
        }
    }
}
 
// OPTION B: Return validation result (no exception)
// Good when: Batch validation, collecting multiple errors
 
public class BulkValidator {
    
    public ValidationResult validate(UserInput input) {
        List<ValidationError> errors = new ArrayList<>();
        
        if (!isValidEmail(input.getEmail())) {
            errors.add(new ValidationError("email", "Invalid format"));
        }
        if (!isValidAge(input.getAge())) {
            errors.add(new ValidationError("age", "Must be 0-150"));
        }
        // ... more validations
        
        return new ValidationResult(errors);
    }
}
 
 
// ===================================================
// SCENARIO: Configuration/Initialization Errors
// RECOMMENDATION: Unchecked
// ===================================================
 
// RATIONALE:
// - If config is invalid, application cannot run
// - No meaningful recovery - fix the config
// - Usually happens at startup, not during operation
 
public class DatabaseConfig {
    
    public static DataSource create(Properties props) {
        String url = props.getProperty("db.url");
        if (url == null || url.isBlank()) {
            throw new ConfigurationException(
                "db.url is required in configuration");
        }
        
        try {
            return new HikariDataSource(buildConfig(props));
        } catch (Exception e) {
            throw new ConfigurationException(
                "Failed to create database connection", e);
        }
    }
}
 
 
// ===================================================
// SCENARIO: Business Rule Violations  
// RECOMMENDATION: Context-dependent
// ===================================================
 
// UNCHECKED: When violation indicates bug or unexpected state
public void cancelOrder(Order order) {
    if (order.getStatus() == OrderStatus.COMPLETED) {
        // This shouldn't happen if UI is correct
        throw new IllegalStateException(
            "Cannot cancel completed order");
    }
    order.setStatus(OrderStatus.CANCELLED);
}
 
// CHECKED: When violation is expected and caller should handle
public void transfer(Account from, Account to, Money amount)
        throws InsufficientFundsException {
    // Insufficient funds is expected operational condition
    // Caller should handle (e.g., show user error, suggest alternatives)
    if (from.getBalance().lessThan(amount)) {
        throw new InsufficientFundsException(from, amount);
    }
    // ... proceed with transfer
}
 
 
// ===================================================
// SCENARIO: Resource Cleanup Failures
// RECOMMENDATION: Usually suppress or log, don't throw new
// ===================================================
 
// RATIONALE:
// - Original exception (if any) is more important
// - Cleanup failures are often secondary concerns
// - Throwing masks the real problem
 
public void processFile(Path path) {
    InputStream input = null;
    try {
        input = Files.newInputStream(path);
        processStream(input);
    } catch (IOException e) {
        throw new ProcessingException("Failed to process: " + path, e);
    } finally {
        if (input != null) {
            try {
                input.close();
            } catch (IOException e) {
                // Log but don't throw - original exception is primary
                logger.warn("Failed to close input stream", e);
            }
        }
    }
}
 
// Even better: Use try-with-resources
public void processFileModern(Path path) {
    try (InputStream input = Files.newInputStream(path)) {
        processStream(input);
    } catch (IOException e) {
        throw new ProcessingException("Failed to process: " + path, e);
    }
    // Close exception is automatically suppressed
}

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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

// ===================================================
// PRINCIPLE 1: Create a Module-Level Base Exception
// ===================================================
 
// Base exception for entire module/subsystem
// Allows catching all module errors with one catch
 
public abstract class PaymentException extends RuntimeException {
    
    protected PaymentException(String message) {
        super(message);
    }
    
    protected PaymentException(String message, Throwable cause) {
        super(message, cause);
    }
}
 
 
// ===================================================
// PRINCIPLE 2: Categorize by Nature/Recoverability
// ===================================================
 
// Category: Transient errors (retryable)
public abstract class TransientPaymentException extends PaymentException {
    
    private final Duration suggestedRetryDelay;
    
    protected TransientPaymentException(String message, Duration retryDelay) {
        super(message);
        this.suggestedRetryDelay = retryDelay;
    }
    
    public Duration getSuggestedRetryDelay() {
        return suggestedRetryDelay;
    }
    
    public boolean isRetryable() {
        return true;
    }
}
 
// Category: Permanent errors (don't retry)
public abstract class PermanentPaymentException extends PaymentException {
    
    protected PermanentPaymentException(String message) {
        super(message);
    }
    
    public boolean isRetryable() {
        return false;
    }
}
 
// Category: Client errors (caller needs to fix something)
public abstract class PaymentClientException extends PermanentPaymentException {
    protected PaymentClientException(String message) {
        super(message);
    }
}
 
 
// ===================================================
// PRINCIPLE 3: Specific Exceptions Under Categories
// ===================================================
 
// Transient exceptions
public class PaymentGatewayTimeoutException extends TransientPaymentException {
    public PaymentGatewayTimeoutException() {
        super("Payment gateway timed out", Duration.ofSeconds(5));
    }
}
 
public class PaymentGatewayUnavailableException extends TransientPaymentException {
    public PaymentGatewayUnavailableException(String reason) {
        super("Payment gateway unavailable: " + reason, Duration.ofMinutes(1));
    }
}
 
// Permanent/Client exceptions  
public class InvalidCardException extends PaymentClientException {
    private final String maskedCardNumber;
    
    public InvalidCardException(String maskedCardNumber, String reason) {
        super("Invalid card " + maskedCardNumber + ": " + reason);
        this.maskedCardNumber = maskedCardNumber;
    }
    
    public String getMaskedCardNumber() {
        return maskedCardNumber;
    }
}
 
public class InsufficientFundsException extends PaymentClientException {
    private final BigDecimal requested;
    private final BigDecimal available;
    
    public InsufficientFundsException(BigDecimal requested, BigDecimal available) {
        super("Insufficient funds: requested " + requested + 
              ", available " + available);
        this.requested = requested;
        this.available = available;
    }
}
 
public class PaymentDeclinedException extends PermanentPaymentException {
    private final String declineCode;
    
    public PaymentDeclinedException(String declineCode, String message) {
        super(message);
        this.declineCode = declineCode;
    }
    
    public String getDeclineCode() {
        return declineCode;
    }
}
 
 
// ===================================================
// USAGE: Flexible Catching at Different Levels
// ===================================================
 
public class PaymentService {
    
    public PaymentResult processPayment(PaymentRequest request) {
        try {
            return gateway.charge(request);
            
        } catch (TransientPaymentException e) {
            // Retry logic for all transient errors
            scheduleRetry(request, e.getSuggestedRetryDelay());
            throw e;
            
        } catch (PaymentClientException e) {
            // Client errors - log and inform user
            logger.info("Payment client error", e);
            return PaymentResult.clientError(e.getMessage());
            
        } catch (PaymentException e) {
            // All other payment errors
            logger.error("Unexpected payment error", e);
            throw e;
        }
    }
}
 
 
// ===================================================
// PRINCIPLE 4: Include Contextual Information
// ===================================================
 
public class OrderProcessingException extends RuntimeException {
    
    private final String orderId;
    private final OrderStatus statusAtFailure;
    private final String operation;
    
    public OrderProcessingException(
            String orderId,
            OrderStatus statusAtFailure,
            String operation,
            String message) {
        super(buildMessage(orderId, operation, message));
        this.orderId = orderId;
        this.statusAtFailure = statusAtFailure;
        this.operation = operation;
    }
    
    private static String buildMessage(
            String orderId, String operation, String message) {
        return String.format(
            "Failed to %s order %s: %s", 
            operation, orderId, message);
    }
    
    // Getters for programmatic access
    public String getOrderId() { return orderId; }
    public OrderStatus getStatusAtFailure() { return statusAtFailure; }
    public String getOperation() { return operation; }
}

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

// JAVA MODERN STRATEGY
 
// 1. Base module exception (unchecked)
public class OrderModuleException extends RuntimeException { /* ... */ }
 
// 2. Specific exceptions for different failure modes
public class OrderNotFoundException extends OrderModuleException { /* ... */ }
public class OrderValidationException extends OrderModuleException { /* ... */ }
 
// 3. Use Optional for "not found" in repositories
public interface OrderRepository {
    Optional<Order> findById(String id);  // Returns empty, not exception
    Order save(Order order);              // Throws on error
}
 
// 4. Service layer converts Optional to exception
public class OrderService {
    public Order getOrder(String id) {
        return repository.findById(id)
            .orElseThrow(() -> new OrderNotFoundException(id));
    }
}
 
// 5. Controller handles at boundary
@RestController
public class OrderController {
    
    @GetMapping("/{id}")
    public ResponseEntity<Order> get(@PathVariable String id) {
        try {
            return ResponseEntity.ok(service.getOrder(id));
        } catch (OrderNotFoundException e) {
            return ResponseEntity.notFound().build();
        }
    }
}
 
// 6. Global exception handler for unexpected errors
@ControllerAdvice
public class GlobalHandler {
    
    @ExceptionHandler(OrderModuleException.class)
    public ResponseEntity<Error> handleOrderError(OrderModuleException e) {
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new Error(e.getMessage()));
    }
}