0
# Exception Management
1

2
Comprehensive exception hierarchy with error codes, types, and detailed error information for proper error handling in distributed client applications. The exception system provides structured error reporting and categorization.
3

4
## Capabilities
5

6
### ClientException
7

8
General exception class for client operations with error code support and nested error types.
9

10
```java { .api }
11
/**
12
 * General exception class for client operations with error code support and nested error types
13
 */
14
public class ClientException extends Exception {
15
    /**
16
     * Serial version UID for serialization
17
     */
18
    public static final long serialVersionUID = -7697654244064441234L;
19
    
20
    /**
21
     * Creates exception with message
22
     * @param message the error message
23
     */
24
    public ClientException(String message);
25
    
26
    /**
27
     * Creates exception with error code
28
     * @param errorCode the numeric error code
29
     */
30
    public ClientException(int errorCode);
31
    
32
    /**
33
     * Creates exception with error code and message
34
     * @param errorCode the numeric error code
35
     * @param message the error message
36
     */
37
    public ClientException(int errorCode, String message);
38
    
39
    /**
40
     * Creates exception with chained exception
41
     * @param chainedException the cause of this exception
42
     */
43
    public ClientException(Throwable chainedException);
44
    
45
    /**
46
     * Creates exception with message and chained exception
47
     * @param message the error message
48
     * @param chainedException the cause of this exception
49
     */
50
    public ClientException(String message, Throwable chainedException);
51
    
52
    /**
53
     * Creates exception with error code, message, and chained exception
54
     * @param errorCode the numeric error code
55
     * @param message the error message
56
     * @param chainedException the cause of this exception
57
     */
58
    public ClientException(int errorCode, String message, Throwable chainedException);
59
    
60
    /**
61
     * Creates exception with error type
62
     * @param error the error type
63
     */
64
    public ClientException(ErrorType error);
65
    
66
    /**
67
     * Creates exception with error type and message
68
     * @param error the error type
69
     * @param message the error message
70
     */
71
    public ClientException(ErrorType error, String message);
72
    
73
    /**
74
     * Creates exception with error type, message, and chained exception
75
     * @param error the error type
76
     * @param message the error message
77
     * @param chainedException the cause of this exception
78
     */
79
    public ClientException(ErrorType error, String message, Throwable chainedException);
80
    
81
    /**
82
     * Returns the error type
83
     * @return the ErrorType associated with this exception
84
     */
85
    public ErrorType getErrorType();
86
    
87
    /**
88
     * Returns the error code
89
     * @return the numeric error code
90
     */
91
    public int getErrorCode();
92
    
93
    /**
94
     * Sets the error code
95
     * @param errorCode the numeric error code to set
96
     */
97
    public void setErrorCode(int errorCode);
98
    
99
    /**
100
     * Returns the error message
101
     * @return the error message
102
     */
103
    public String getErrorMessage();
104
    
105
    /**
106
     * Sets the error message
107
     * @param msg the error message to set
108
     */
109
    public void setErrorMessage(String msg);
110
    
111
    /**
112
     * Returns the error object
113
     * @return additional error context object
114
     */
115
    public Object getErrorObject();
116
    
117
    /**
118
     * Sets the error object
119
     * @param errorObject additional error context object
120
     */
121
    public void setErrorObject(Object errorObject);
122
    
123
    /**
124
     * Returns internal message for the exception
125
     * @return internal diagnostic message
126
     */
127
    public String getInternalMessage();
128
    
129
    /**
130
     * Returns error codes mapping for a class
131
     * @param clazz the class to get error codes for
132
     * @return HashMap mapping error names to codes
133
     */
134
    public static HashMap getErrorCodes(Class clazz);
135
    
136
    /**
137
     * Error type enumeration categorizing different types of client errors
138
     */
139
    public enum ErrorType {
140
        /** General unspecified error */
141
        GENERAL,
142
        /** Configuration-related error */
143
        CONFIGURATION,
144
        /** Maximum retries on same server exceeded */
145
        NUMBEROF_RETRIES_EXEEDED,
146
        /** Maximum retries across servers exceeded */
147
        NUMBEROF_RETRIES_NEXTSERVER_EXCEEDED,
148
        /** Socket timeout during operation */
149
        SOCKET_TIMEOUT_EXCEPTION,
150
        /** Read timeout during operation */
151
        READ_TIMEOUT_EXCEPTION,
152
        /** Unknown host error */
153
        UNKNOWN_HOST_EXCEPTION,
154
        /** Connection establishment error */
155
        CONNECT_EXCEPTION,
156
        /** Client-side throttling applied */
157
        CLIENT_THROTTLED,
158
        /** Server-side throttling detected */
159
        SERVER_THROTTLED,
160
        /** No network route to host */
161
        NO_ROUTE_TO_HOST_EXCEPTION,
162
        /** Required data missing from cache */
163
        CACHE_MISSING
164
    }
165
}
166
```
167

168
**Usage Examples:**
169

170
```java
171
import com.netflix.client.ClientException;
172
import com.netflix.client.ClientException.ErrorType;
173

174
// Basic exception with message
175
throw new ClientException("Failed to connect to service");
176

177
// Exception with error type
178
throw new ClientException(ErrorType.CONNECT_EXCEPTION, "Could not establish connection");
179

180
// Exception with error code and chained cause
181
try {
182
    // Some network operation
183
} catch (SocketTimeoutException e) {
184
    throw new ClientException(ErrorType.SOCKET_TIMEOUT_EXCEPTION, 
185
                             "Request timed out after 5 seconds", e);
186
}
187

188
// Exception handling with type checking
189
try {
190
    // Client operation
191
} catch (ClientException e) {
192
    switch (e.getErrorType()) {
193
        case SOCKET_TIMEOUT_EXCEPTION:
194
            // Handle timeout specifically
195
            logger.warn("Request timed out, will retry");
196
            break;
197
        case CONNECT_EXCEPTION:
198
            // Handle connection issues
199
            logger.error("Connection failed: " + e.getErrorMessage());
200
            break;
201
        case CLIENT_THROTTLED:
202
            // Handle throttling
203
            logger.info("Request was throttled, backing off");
204
            Thread.sleep(1000);
205
            break;
206
        default:
207
            logger.error("Unexpected client error", e);
208
    }
209
}
210
```
211

212
### UnexpectedHttpResponseException
213

214
Exception thrown when HTTP response is unexpected.
215

216
```java { .api }
217
/**
218
 * Exception thrown when HTTP response is unexpected
219
 */
220
public class UnexpectedHttpResponseException extends Exception {
221
    /**
222
     * Serial version UID for serialization
223
     */
224
    public static final long serialVersionUID = 1L;
225
    
226
    /**
227
     * Creates exception with HTTP status information
228
     * @param statusCode the HTTP status code
229
     * @param statusLine the HTTP status line
230
     */
231
    public UnexpectedHttpResponseException(int statusCode, String statusLine);
232
    
233
    /**
234
     * Returns HTTP status code
235
     * @return the HTTP status code that caused this exception
236
     */
237
    public int getStatusCode();
238
    
239
    /**
240
     * Returns HTTP status line
241
     * @return the HTTP status line that caused this exception
242
     */
243
    public String getStatusLine();
244
}
245
```
246

247
**Usage Examples:**
248

249
```java
250
import com.netflix.client.http.UnexpectedHttpResponseException;
251

252
// In HTTP client implementation
253
public void handleHttpResponse(int statusCode, String statusLine) throws UnexpectedHttpResponseException {
254
    if (statusCode >= 400) {
255
        throw new UnexpectedHttpResponseException(statusCode, statusLine);
256
    }
257
}
258

259
// Exception handling
260
try {
261
    // HTTP request
262
} catch (UnexpectedHttpResponseException e) {
263
    int status = e.getStatusCode();
264
    String line = e.getStatusLine();
265
    
266
    if (status >= 500) {
267
        // Server error - might be retriable
268
        logger.warn("Server error: {} - {}", status, line);
269
    } else if (status >= 400) {
270
        // Client error - typically not retriable
271
        logger.error("Client error: {} - {}", status, line);
272
    }
273
}
274
```
275

276
### ClientSslSocketFactoryException
277

278
Exception for SSL socket factory problems.
279

280
```java { .api }
281
/**
282
 * Exception for SSL socket factory problems
283
 */
284
public class ClientSslSocketFactoryException extends Exception {
285
    /**
286
     * Serial version UID for serialization
287
     */
288
    public static final long serialVersionUID = 1L;
289
    
290
    /**
291
     * Creates SSL exception with message and cause
292
     * @param message the error message
293
     * @param cause the underlying cause
294
     */
295
    public ClientSslSocketFactoryException(String message, Throwable cause);
296
}
297
```
298

299
**Usage Examples:**
300

301
```java
302
import com.netflix.client.ssl.ClientSslSocketFactoryException;
303

304
// In SSL context factory
305
public SSLContext createSSLContext() throws ClientSslSocketFactoryException {
306
    try {
307
        // SSL context creation logic
308
        return sslContext;
309
    } catch (KeyStoreException e) {
310
        throw new ClientSslSocketFactoryException("Failed to load keystore", e);
311
    } catch (NoSuchAlgorithmException e) {
312
        throw new ClientSslSocketFactoryException("SSL algorithm not available", e);
313
    }
314
}
315

316
// Exception handling
317
try {
318
    SSLContext context = factory.createSSLContext();
319
} catch (ClientSslSocketFactoryException e) {
320
    logger.error("SSL configuration error: " + e.getMessage(), e.getCause());
321
    // Fall back to default SSL configuration
322
}
323
```
324

325
### Exception Handling Patterns
326

327
```java
328
/**
329
 * Comprehensive exception handling for client operations
330
 */
331
public class RobustClient {
332
    private static final Logger logger = LoggerFactory.getLogger(RobustClient.class);
333
    
334
    public void executeRequest(ClientRequest request) {
335
        try {
336
            // Execute client request
337
            performRequest(request);
338
            
339
        } catch (ClientException e) {
340
            handleClientException(e);
341
        } catch (UnexpectedHttpResponseException e) {
342
            handleHttpException(e);
343
        } catch (ClientSslSocketFactoryException e) {
344
            handleSslException(e);
345
        } catch (Exception e) {
346
            handleGenericException(e);
347
        }
348
    }
349
    
350
    private void handleClientException(ClientException e) {
351
        ErrorType errorType = e.getErrorType();
352
        int errorCode = e.getErrorCode();
353
        String message = e.getErrorMessage();
354
        
355
        // Log with appropriate level based on error type
356
        switch (errorType) {
357
            case SOCKET_TIMEOUT_EXCEPTION:
358
            case READ_TIMEOUT_EXCEPTION:
359
                logger.warn("Timeout error ({}): {}", errorCode, message);
360
                // Might be retriable
361
                break;
362
                
363
            case CONNECT_EXCEPTION:
364
            case NO_ROUTE_TO_HOST_EXCEPTION:
365
                logger.error("Connection error ({}): {}", errorCode, message);
366
                // Check if service is down
367
                break;
368
                
369
            case CLIENT_THROTTLED:
370
            case SERVER_THROTTLED:
371
                logger.info("Throttling detected ({}): {}", errorCode, message);
372
                // Implement backoff strategy
373
                break;
374
                
375
            case CONFIGURATION:
376
                logger.error("Configuration error ({}): {}", errorCode, message);
377
                // Fix configuration
378
                break;
379
                
380
            default:
381
                logger.error("Client error ({}): {}", errorCode, message, e);
382
        }
383
        
384
        // Additional error context
385
        Object errorObject = e.getErrorObject();
386
        if (errorObject != null) {
387
            logger.debug("Error context: {}", errorObject);
388
        }
389
    }
390
    
391
    private void handleHttpException(UnexpectedHttpResponseException e) {
392
        int statusCode = e.getStatusCode();
393
        String statusLine = e.getStatusLine();
394
        
395
        if (statusCode >= 500) {
396
            logger.warn("Server error: {} {}", statusCode, statusLine);
397
            // Server error - might retry with backoff
398
        } else if (statusCode >= 400) {
399
            logger.error("Client error: {} {}", statusCode, statusLine);
400
            // Client error - fix request before retry
401
        }
402
    }
403
    
404
    private void handleSslException(ClientSslSocketFactoryException e) {
405
        logger.error("SSL configuration error: {}", e.getMessage(), e);
406
        // Check SSL certificates and configuration
407
    }
408
    
409
    private void handleGenericException(Exception e) {
410
        logger.error("Unexpected error during request execution", e);
411
        // Generic error handling
412
    }
413
}
414
```
415

416
### Error Recovery Strategies
417

418
```java
419
/**
420
 * Example of error recovery with exponential backoff
421
 */
422
public class RetryableClient {
423
    private static final int MAX_RETRIES = 3;
424
    private static final long BASE_DELAY_MS = 1000;
425
    
426
    public void executeWithRecovery(ClientRequest request) throws ClientException {
427
        int attempt = 0;
428
        
429
        while (attempt <= MAX_RETRIES) {
430
            try {
431
                performRequest(request);
432
                return; // Success
433
                
434
            } catch (ClientException e) {
435
                if (!isRetriable(e) || attempt == MAX_RETRIES) {
436
                    throw e; // Don't retry or max attempts reached
437
                }
438
                
439
                attempt++;
440
                long delay = calculateBackoffDelay(attempt);
441
                
442
                logger.warn("Request failed (attempt {}), retrying in {}ms: {}", 
443
                          attempt, delay, e.getErrorMessage());
444
                
445
                try {
446
                    Thread.sleep(delay);
447
                } catch (InterruptedException ie) {
448
                    Thread.currentThread().interrupt();
449
                    throw new ClientException("Request interrupted during retry", ie);
450
                }
451
            }
452
        }
453
    }
454
    
455
    private boolean isRetriable(ClientException e) {
456
        switch (e.getErrorType()) {
457
            case SOCKET_TIMEOUT_EXCEPTION:
458
            case READ_TIMEOUT_EXCEPTION:
459
            case CONNECT_EXCEPTION:
460
                return true;
461
            case CLIENT_THROTTLED:
462
            case SERVER_THROTTLED:
463
                return true;
464
            default:
465
                return false;
466
        }
467
    }
468
    
469
    private long calculateBackoffDelay(int attempt) {
470
        return BASE_DELAY_MS * (1L << (attempt - 1)); // Exponential backoff
471
    }
472
}