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

// WITHOUT EXCEPTION CHAINING - Information Loss
 
// Layer 1: Database
public User findById(String id) throws SQLException {
    return jdbcTemplate.queryForObject(sql, id);
}
 
// Layer 2: Repository
public User getUser(String id) throws UserRepositoryException {
    try {
        return database.findById(id);
    } catch (SQLException e) {
        // ❌ WRONG: Original exception discarded!
        throw new UserRepositoryException("Failed to get user");
        // Stack trace now starts HERE, not at the actual failure
    }
}
 
// Layer 3: Service
public UserDTO loadUserProfile(String id) throws ServiceException {
    try {
        User user = repository.getUser(id);
        return mapper.toDTO(user);
    } catch (UserRepositoryException e) {
        // ❌ Even worse: Each layer loses more information
        throw new ServiceException("Profile load failed");
    }
}
 
// When this fails, the stack trace shows:
// ServiceException: Profile load failed
//   at ProfileService.loadUserProfile(ProfileService.java:42)
//
// Missing: WHERE in the database did it fail? What was the SQL error?
// Was it a constraint violation? Connection timeout? Syntax error?
// WE DON'T KNOW. That information was destroyed.

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

// WITH EXCEPTION CHAINING - Complete Diagnostic Trail
 
// Layer 1: Database (unchanged)
public User findById(String id) throws SQLException {
    return jdbcTemplate.queryForObject(sql, id);
}
 
// Layer 2: Repository
public User getUser(String id) throws UserRepositoryException {
    try {
        return database.findById(id);
    } catch (SQLException e) {
        // ✅ CORRECT: Original exception is the CAUSE
        throw new UserRepositoryException("Failed to get user: " + id, e);
    }
}
 
// Layer 3: Service
public UserDTO loadUserProfile(String id) throws ServiceException {
    try {
        User user = repository.getUser(id);
        return mapper.toDTO(user);
    } catch (UserRepositoryException e) {
        // ✅ Chain continues: repository exception becomes cause
        throw new ServiceException("Profile load failed for: " + id, e);
    }
}
 
// When this fails, the FULL stack trace shows:
// ServiceException: Profile load failed for: user-123
//   at ProfileService.loadUserProfile(ProfileService.java:42)
// Caused by: UserRepositoryException: Failed to get user: user-123
//   at UserRepository.getUser(UserRepository.java:28)
// Caused by: SQLException: ORA-00942: table or view does not exist
//   at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:452)
//   at ...
//
// NOW WE KNOW: The users table doesn't exist! Easy to diagnose.

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

/**
 * Examples of when to wrap vs. when to rethrow.
 */
public class WhenToWrapExamples {
    
    // ✅ WRAP: Crossing architectural boundary
    // Infrastructure exception → Domain exception
    public User getUserById(String id) throws UserNotFoundException {
        try {
            Row row = database.query("SELECT * FROM users WHERE id = ?", id);
            if (row == null) {
                throw new UserNotFoundException("User not found: " + id);
            }
            return mapToUser(row);
        } catch (SQLException e) {
            // Wrap: Callers shouldn't know we use SQL
            throw new DataAccessException("Failed to retrieve user: " + id, e);
        }
    }
    
    // ✅ WRAP: API boundary
    // Internal exception → Public API exception
    public class PaymentClient {
        public PaymentResult charge(PaymentRequest request) 
                throws PaymentException {
            try {
                HttpResponse response = httpClient.post("/charge", request);
                return parseResponse(response);
            } catch (HttpException e) {
                // Wrap: Public API shouldn't expose HTTP details
                throw new PaymentException(
                    "Payment processing failed", 
                    PaymentErrorCode.SERVICE_ERROR, 
                    e);
            } catch (JsonParseException e) {
                // Wrap: Response parsing is internal detail
                throw new PaymentException(
                    "Invalid response from payment provider",
                    PaymentErrorCode.PROVIDER_ERROR,
                    e);
            }
        }
    }
    
    // ✅ WRAP: Adding semantic meaning
    public User authenticate(String username, String password) 
            throws AuthenticationException {
        try {
            User user = userRepository.findByUsername(username);
            if (user == null || !passwordEncoder.matches(password, user.getHash())) {
                throw new InvalidCredentialsException("Invalid username or password");
            }
            return user;
        } catch (DataAccessException e) {
            // Wrap with security-relevant type
            throw new AuthenticationException("Authentication system unavailable", e);
        }
    }
    
    // ✅ RETHROW: Same abstraction level
    public void processOrder(Order order) throws OrderProcessingException {
        // Both are at "order processing" abstraction level
        validateOrder(order);  // throws OrderValidationException
        reserveInventory(order);  // throws OrderProcessingException
        // Let these propagate unchanged - they're already at right level
    }
    
    // ✅ RETHROW: Just adding logging
    public void importantOperation() throws CriticalException {
        try {
            performCriticalWork();
        } catch (CriticalException e) {
            logger.error("Critical operation failed", e);
            throw e;  // Rethrow unchanged after logging
        }
    }
    
    // ❌ ANTI-PATTERN: Wrapping at same level (pointless)
    public void unnecessaryWrapping() throws ServiceException {
        try {
            callOtherService();
        } catch (ServiceException e) {
            // ❌ Just adds noise - no new information
            throw new ServiceException("Service call failed", 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

/**
 * Enriching exceptions with contextual information at each layer.
 */
 
// Layer 1: Database
// Only knows about SQL
public class UserDao {
    public User findById(String id) throws DataAccessException {
        try {
            return jdbcTemplate.queryForObject(sql, id);
        } catch (EmptyResultDataAccessException e) {
            throw new RecordNotFoundException("users", id, e);
        } catch (DataAccessException e) {
            // Add SQL-level context
            throw new DataAccessException(
                String.format("Query failed: table=users, id=%s", id), e);
        }
    }
}
 
// Layer 2: Repository
// Knows about domain entities
public class UserRepository {
    public User getUser(UserId userId) throws UserException {
        try {
            return userDao.findById(userId.getValue());
        } catch (RecordNotFoundException e) {
            throw new UserNotFoundException(userId, e);
        } catch (DataAccessException e) {
            // Add domain context
            throw new UserDataAccessException(
                String.format("Failed to load user: userId=%s", userId), e);
        }
    }
}
 
// Layer 3: Service
// Knows about business operations
public class OrderService {
    public Order createOrder(OrderRequest request) throws OrderException {
        String orderId = generateOrderId();
        
        try {
            User user = userRepository.getUser(request.getUserId());
            Order order = buildOrder(orderId, user, request);
            return orderRepository.save(order);
            
        } catch (UserNotFoundException e) {
            // Add operation context
            throw new OrderCreationException(
                String.format("Order creation failed: orderId=%s, reason=user not found", 
                              orderId),
                OrderErrorCode.USER_NOT_FOUND,
                e);
        } catch (DataAccessException e) {
            // Add operation context
            throw new OrderCreationException(
                String.format("Order creation failed: orderId=%s, userId=%s, items=%d",
                              orderId, request.getUserId(), request.getItems().size()),
                OrderErrorCode.DATA_ACCESS_ERROR,
                e);
        }
    }
}
 
// Layer 4: Controller
// Knows about the request
@RestController
public class OrderController {
    
    @PostMapping("/orders")
    public ResponseEntity<OrderResponse> createOrder(
            @RequestBody OrderRequest request,
            @RequestHeader("X-Request-ID") String requestId) {
        
        try {
            Order order = orderService.createOrder(request);
            return ResponseEntity.ok(new OrderResponse(order));
            
        } catch (OrderCreationException e) {
            // Add request context
            logger.error("Order creation failed. RequestId={}, UserId={}, Error={}",
                        requestId, request.getUserId(), e.getMessage(), e);
            
            return ResponseEntity.status(mapToHttpStatus(e.getErrorCode()))
                    .body(OrderResponse.error(e.getErrorCode(), e.getMessage()));
        }
    }
}
 
// The final stack trace contains ALL context:
// OrderCreationException: Order creation failed: orderId=ORD-123, reason=user not found
//   at OrderService.createOrder(OrderService.java:42)
// Caused by: UserNotFoundException: User not found: userId=USR-456
//   at UserRepository.getUser(UserRepository.java:28)
// Caused by: RecordNotFoundException: Record not found: table=users, id=USR-456
//   at UserDao.findById(UserDao.java:15)
// Caused by: EmptyResultDataAccessException: ...

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

/**
 * Exception translation at architectural boundaries.
 */
public class ExceptionTranslation {
    
    // PATTERN 1: Translator class for complex mappings
    public class PaymentExceptionTranslator {
        
        public PaymentException translate(StripeException stripeEx) {
            // Map vendor-specific errors to domain errors
            return switch (stripeEx.getCode()) {
                case "card_declined" -> new PaymentDeclinedException(
                    "Card was declined",
                    stripeEx.getDeclineCode(),
                    stripeEx);
                    
                case "expired_card" -> new InvalidPaymentMethodException(
                    "Card has expired",
                    PaymentErrorCode.CARD_EXPIRED,
                    stripeEx);
                    
                case "insufficient_funds" -> new PaymentDeclinedException(
                    "Insufficient funds",
                    "insufficient_funds",
                    stripeEx);
                    
                case "rate_limit" -> new PaymentServiceException(
                    "Payment service rate limited",
                    PaymentErrorCode.RATE_LIMITED,
                    true,  // isRetryable
                    stripeEx);
                    
                default -> new PaymentServiceException(
                    "Payment processing failed: " + stripeEx.getMessage(),
                    PaymentErrorCode.UNKNOWN,
                    false,
                    stripeEx);
            };
        }
    }
    
    // PATTERN 2: Adapter that handles translation
    public class StripePaymentAdapter implements PaymentGateway {
        private final PaymentExceptionTranslator translator = 
            new PaymentExceptionTranslator();
        
        @Override
        public PaymentResult charge(PaymentRequest request) throws PaymentException {
            try {
                Charge charge = Charge.create(toStripeParams(request));
                return toPaymentResult(charge);
            } catch (StripeException e) {
                throw translator.translate(e);
            }
        }
    }
    
    // PATTERN 3: Centralized exception mapping for APIs
    @ControllerAdvice
    public class GlobalExceptionHandler {
        
        @ExceptionHandler(DomainException.class)
        public ResponseEntity<ErrorResponse> handleDomainException(
                DomainException ex, WebRequest request) {
            
            // Translate domain exceptions to HTTP responses
            HttpStatus status = mapToStatus(ex);
            ErrorResponse response = new ErrorResponse(
                ex.getErrorCode(),
                ex.getMessage(),
                request.getDescription(false)
            );
            
            // Log with full chain for debugging
            logger.error("Domain exception occurred", ex);
            
            return ResponseEntity.status(status).body(response);
        }
        
        private HttpStatus mapToStatus(DomainException ex) {
            return switch (ex.getErrorCode().getCategory()) {
                case VALIDATION -> HttpStatus.BAD_REQUEST;
                case NOT_FOUND -> HttpStatus.NOT_FOUND;
                case AUTHENTICATION -> HttpStatus.UNAUTHORIZED;
                case AUTHORIZATION -> HttpStatus.FORBIDDEN;
                case CONFLICT -> HttpStatus.CONFLICT;
                case RATE_LIMIT -> HttpStatus.TOO_MANY_REQUESTS;
                default -> HttpStatus.INTERNAL_SERVER_ERROR;
            };
        }
    }
}

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

/**
 * Common exception wrapping anti-patterns.
 */
public class WrappingAntiPatterns {
    
    // ❌ ANTI-PATTERN 1: Breaking the chain
    public void brokenChain() throws CustomException {
        try {
            operation();
        } catch (IOException e) {
            // ❌ Original exception NOT passed as cause
            throw new CustomException("Operation failed");
            // Debugging: "Why did it fail?" - Unknown, chain broken
        }
    }
    
    // ✅ CORRECT
    public void preservedChain() throws CustomException {
        try {
            operation();
        } catch (IOException e) {
            throw new CustomException("Operation failed", e);  // With cause
        }
    }
    
    // ❌ ANTI-PATTERN 2: Wrapping everything at once
    public void massiveWrap() throws ServiceException {
        try {
            // Many operations lumped together
            config = loadConfig();
            db = connectDatabase();
            user = authenticate();
            data = fetchData();
            result = processData(data);
        } catch (Exception e) {
            // ❌ All failures get same generic message
            throw new ServiceException("Service operation failed", e);
        }
    }
    
    // ✅ CORRECT: Wrap specifically where needed
    public void specificWrapping() throws ServiceException {
        try {
            config = loadConfig();
        } catch (ConfigException e) {
            throw new ServiceException("Service configuration failed", e);
        }
        
        try {
            db = connectDatabase();
        } catch (DatabaseException e) {
            throw new ServiceException("Database connection failed", e);
        }
        // Each failure has specific context
    }
    
    // ❌ ANTI-PATTERN 3: Over-wrapping (unnecessary layers)
    public void overWrapping() throws MyException {
        try {
            try {
                try {
                    operation();
                } catch (IOException e) {
                    throw new LowLevelException("IO failed", e);
                }
            } catch (LowLevelException e) {
                throw new MidLevelException("Low level failed", e);
            }
        } catch (MidLevelException e) {
            throw new MyException("Mid level failed", e);  // ❌ Too many layers
        }
    }
    // Stack trace becomes:
    // MyException → MidLevelException → LowLevelException → IOException
    // Three layers of "failed" with no useful info added
    
    // ✅ CORRECT: Wrap only at meaningful boundaries
    public void appropriateWrapping() throws MyException {
        try {
            operation();
        } catch (IOException e) {
            // One wrap, at the layer boundary
            throw new MyException("Operation failed due to IO error", e);
        }
    }
    
    // ❌ ANTI-PATTERN 4: Losing exception properties
    public void losingProperties() throws CustomException {
        try {
            operation();
        } catch (DetailedException e) {
            // ❌ e has errorCode, affectedResource, timestamp...
            // All lost because we only keep the message
            throw new CustomException(e.getMessage(), e);
        }
    }
    
    // ✅ CORRECT: Preserve important properties
    public void preservingProperties() throws CustomException {
        try {
            operation();
        } catch (DetailedException e) {
            throw new CustomException(
                e.getMessage(),
                e.getErrorCode(),      // Preserve error code
                e.getAffectedResource(), // Preserve context
                e);                      // Preserve cause
        }
    }
}