0
# Exception Handling
1

2
The exception handling system in tinylog-impl provides flexible transformation and filtering of exceptions and stack traces, allowing customization of how errors are logged and displayed.
3

4
## Capabilities
5

6
### Throwable Filter Interface
7

8
Base interface for all throwable transformation filters.
9

10
```java { .api }
11
/**
12
 * Interface for filters that transform throwable data
13
 */
14
interface ThrowableFilter {
15
    /**
16
     * Transform throwable data according to filter logic
17
     * @param origin Original throwable data
18
     * @return Transformed throwable data
19
     */
20
    ThrowableData filter(ThrowableData origin);
21
}
22
```
23

24
### Throwable Data Interface
25

26
Interface representing throwable information that can be processed by filters.
27

28
```java { .api }
29
/**
30
 * Interface for accessing throwable data
31
 */
32
interface ThrowableData {
33
    /**
34
     * Get the throwable class name
35
     * @return Fully qualified class name
36
     */
37
    String getClassName();
38
    
39
    /**
40
     * Get the throwable message
41
     * @return Exception message or null
42
     */
43
    String getMessage();
44
    
45
    /**
46
     * Get the stack trace elements
47
     * @return List of stack trace elements
48
     */
49
    List<StackTraceElement> getStackTrace();
50
    
51
    /**
52
     * Get the cause of this throwable
53
     * @return Cause throwable data or null
54
     */
55
    ThrowableData getCause();
56
}
57
```
58

59
### Keep Throwable Filter
60

61
Preserves complete throwable information including full stack traces and cause chains.
62

63
```java { .api }
64
/**
65
 * Filter that preserves complete throwable information
66
 */
67
class KeepThrowableFilter extends AbstractStackTraceElementsFilter {
68
    /**
69
     * Default constructor preserving all throwable data
70
     */
71
    public KeepThrowableFilter();
72
    
73
    /**
74
     * Constructor with filter arguments
75
     * @param arguments Configuration arguments for filtering
76
     */
77
    public KeepThrowableFilter(String arguments);
78
}
79
```
80

81
**Configuration Examples:**
82

83
```properties
84
# Keep full throwable information (default)
85
writer=console
86
writer.exception=keep
87

88
# Keep throwable but limit stack trace depth
89
writer=file
90
writer.file=app.log
91
writer.exception=keep
92
writer.exception.depth=20
93
```
94

95
### Strip Throwable Filter
96

97
Removes stack trace elements while preserving exception class and message information.
98

99
```java { .api }
100
/**
101
 * Filter that strips stack trace elements but keeps exception info
102
 */
103
class StripThrowableFilter extends AbstractStackTraceElementsFilter {
104
    /**
105
     * Default constructor that strips all stack trace elements
106
     */
107
    public StripThrowableFilter();
108
}
109
```
110

111
**Configuration Examples:**
112

113
```properties
114
# Strip stack traces, keep only exception class and message
115
writer=console
116
writer.exception=strip
117

118
# Multiple writers with different exception handling
119
writer=console
120
writer.exception=strip
121

122
writer2=file
123
writer2.file=detailed.log
124
writer2.exception=keep
125
```
126

127
### Drop Cause Throwable Filter
128

129
Removes cause chain from exceptions, keeping only the top-level exception information.
130

131
```java { .api }
132
/**
133
 * Filter that drops cause throwables from the chain
134
 */
135
class DropCauseThrowableFilter extends AbstractThrowableFilter {
136
    /**
137
     * Default constructor that removes all cause information
138
     */
139
    public DropCauseThrowableFilter();
140
}
141
```
142

143
**Configuration Examples:**
144

145
```properties
146
# Drop cause chain, keep only primary exception
147
writer=console
148
writer.exception=drop cause
149

150
# Useful for reducing log verbosity
151
writer=file
152
writer.file=summary.log
153
writer.exception=drop cause
154
writer.format={date} {level}: {message} - {exception}
155
```
156

157
### Unpack Throwable Filter
158

159
Unpacks wrapped exceptions to reveal the underlying root cause, useful for handling framework exceptions that wrap application exceptions.
160

161
```java { .api }
162
/**
163
 * Filter that unpacks wrapped exceptions to reveal root causes
164
 */
165
class UnpackThrowableFilter extends AbstractThrowableFilter {
166
    /**
167
     * Default constructor that unpacks common wrapper exceptions
168
     */
169
    public UnpackThrowableFilter();
170
    
171
    /**
172
     * Constructor with custom wrapper class names
173
     * @param wrapperClasses Class names of exceptions to unwrap
174
     */
175
    public UnpackThrowableFilter(String... wrapperClasses);
176
}
177
```
178

179
**Configuration Examples:**
180

181
```properties
182
# Unpack common wrapper exceptions
183
writer=console
184
writer.exception=unpack
185

186
# Unpack specific wrapper types
187
writer=file
188
writer.file=app.log
189
writer.exception=unpack
190
writer.exception.classes=java.util.concurrent.ExecutionException,javax.servlet.ServletException
191
```
192

193
### Abstract Base Classes
194

195
Base classes providing common functionality for throwable filters.
196

197
```java { .api }
198
/**
199
 * Abstract base class for throwable filters
200
 */
201
abstract class AbstractThrowableFilter implements ThrowableFilter {
202
    /**
203
     * Create filter from configuration properties
204
     * @param properties Configuration properties
205
     */
206
    protected AbstractThrowableFilter(Map<String, String> properties);
207
    
208
    /**
209
     * Apply filter transformation to throwable data
210
     * @param data Original throwable data
211
     * @return Transformed throwable data
212
     */
213
    protected abstract ThrowableData transform(ThrowableData data);
214
}
215

216
/**
217
 * Abstract base class for filters that work with stack trace elements
218
 */
219
abstract class AbstractStackTraceElementsFilter extends AbstractThrowableFilter {
220
    /**
221
     * Filter stack trace elements according to implementation logic
222
     * @param elements Original stack trace elements
223
     * @return Filtered stack trace elements
224
     */
225
    protected abstract List<StackTraceElement> filterStackTraceElements(List<StackTraceElement> elements);
226
    
227
    /**
228
     * Get maximum number of stack trace elements to process
229
     * @return Maximum elements or -1 for unlimited
230
     */
231
    protected int getMaxStackTraceElements();
232
}
233
```
234

235
### Throwable Data Implementations
236

237
Concrete implementations for handling throwable data.
238

239
```java { .api }
240
/**
241
 * Wrapper implementation for throwable data
242
 */
243
class ThrowableWrapper implements ThrowableData {
244
    /**
245
     * Create wrapper from actual throwable
246
     * @param throwable Source throwable
247
     */
248
    public ThrowableWrapper(Throwable throwable);
249
    
250
    /**
251
     * Create wrapper with custom data
252
     * @param className Exception class name
253
     * @param message Exception message
254
     * @param stackTrace Stack trace elements
255
     * @param cause Cause throwable data
256
     */
257
    public ThrowableWrapper(String className, String message, 
258
                           List<StackTraceElement> stackTrace, ThrowableData cause);
259
}
260

261
/**
262
 * Storage implementation for throwable data
263
 */
264
class ThrowableStore implements ThrowableData {
265
    /**
266
     * Create store from throwable wrapper
267
     * @param wrapper Source throwable wrapper
268
     */
269
    public ThrowableStore(ThrowableWrapper wrapper);
270
    
271
    /**
272
     * Create store with explicit data
273
     * @param className Exception class name
274
     * @param message Exception message
275
     * @param stackTrace Stack trace elements
276
     * @param cause Cause throwable data
277
     */
278
    public ThrowableStore(String className, String message,
279
                         List<StackTraceElement> stackTrace, ThrowableData cause);
280
}
281
```
282

283
## Filter Combinations
284

285
Multiple exception filters can be chained together to create sophisticated exception processing pipelines.
286

287
### Common Filter Chains
288

289
**Unpack then Strip:**
290
```properties
291
# First unpack wrapped exceptions, then strip stack traces
292
writer=console
293
writer.exception=unpack,strip
294
```
295

296
**Keep with Depth Limit:**
297
```properties
298
# Keep exceptions but limit stack trace depth
299
writer=file
300
writer.file=app.log
301
writer.exception=keep
302
writer.exception.depth=15
303
```
304

305
**Unpack then Drop Cause:**
306
```properties
307
# Unpack wrappers, then remove cause chain
308
writer=console
309
writer.exception=unpack,drop cause
310
```
311

312
## Usage Examples
313

314
**Basic Exception Configuration:**
315

316
```properties
317
# Simple console output with full exception details
318
writer=console
319
writer.format={date: HH:mm:ss} {level}: {message}
320
writer.exception=keep
321

322
# File output with stripped stack traces for cleaner logs
323
writer2=file
324
writer2.file=summary.log
325
writer2.format={message}
326
writer2.exception=strip
327
```
328

329
**Advanced Exception Filtering:**
330

331
```properties
332
# Console: stripped for readability
333
writer=console
334
writer.exception=strip
335
writer.format={level}: {message} [{exception}]
336

337
# File: full details for debugging
338
writer2=file
339
writer2.file=debug.log
340
writer2.exception=keep
341
writer2.exception.depth=50
342

343
# Error file: unpacked exceptions only
344
writer3=file
345
writer3.file=errors.log
346
writer3.level=ERROR
347
writer3.exception=unpack
348
writer3.format={date} ERROR: {message}{newline}{exception}
349
```
350

351
**Environment-Specific Configuration:**
352

353
```properties
354
# Development: full exception details
355
writer=console
356
writer.exception=keep
357
writer.format={date: HH:mm:ss.SSS} [{level}] {class}.{method}(): {message}{newline}{exception}
358

359
# Production: minimal exception info for performance
360
writer=file
361
writer.file=/var/log/app.log  
362
writer.exception=strip
363
writer.format={date} {level}: {message} - {exception}
364
```
365

366
**Exception Filter Chaining:**
367

368
```properties
369
# Complex filter chain: unpack wrappers, then limit depth, then drop causes
370
writer=file
371
writer.file=processed.log
372
writer.exception=unpack,keep,drop cause
373
writer.exception.depth=10
374
writer.exception.classes=java.lang.reflect.InvocationTargetException
375

376
# Alternative: different processing for different levels
377
writer=console
378
writer.level=INFO
379
writer.exception=strip
380

381
writer2=file
382
writer2.file=errors.log
383
writer2.level=ERROR
384
writer2.exception=keep
385
writer2.exception.depth=25
386
```
387

388
**Custom Wrapper Classes:**
389

390
```properties
391
# Unpack specific application wrapper exceptions
392
writer=file
393
writer.file=app.log
394
writer.exception=unpack
395
writer.exception.classes=com.myapp.ServiceException,com.myapp.BusinessException,java.util.concurrent.ExecutionException
396
```
397

398
**Performance-Optimized Exception Handling:**
399

400
```properties
401
# High-performance logging with minimal exception overhead
402
writer=file
403
writer.file=perf.log
404
writer.exception=drop cause
405
writer.format={date} {level}: {message}
406
writer.buffered=true
407
writer.writingthread=true
408
```