C
- the type of the cause exceptions.X
- the type of the thrown exceptions.@NotThreadSafe public interface ExceptionHandler<C extends Exception,X extends Exception>
Optionally, the implementation may perform additional operations such as logging the cause exception or storing it for later use. This implies that the implementation may be stateful and mutable, which in turn implies that the cooperative algorithm should not bypass this interface, i.e. it should never simply create and throw an exception without calling this exception handler. Otherwise some information, such as previous cause exceptions for example, would get lost.
In general, the type parameter for the cause exception is determined by the cooperative algorithm, whereas the type parameter for the thrown exception is determined by the client application. Where possible, the cooperative algorithm should declare generic method signatures in order to enable the client application to select the type of the thrown exception as desired (see below).
As an example for a cooperative algorithm which may benefit from using this interface, consider the recursive copying of a directory tree: Among many others, the copy algorithm may encounter the following exceptional conditions:
Now the implementation may decide whether the copy algorithm shall proceed with the remaining files and directories in the tree or if not, if the cause exception should be wrapped in another exception in order to enable diagnosing the situation by its client application.
Ideally, the copy algorithm could use two different exception handlers: One for any exception when reading from a source file and another one for any exception when writing to a destination file. If these exception handlers would map any cause to a different exception type, this would enable the client application to analyze the situation and take appropriate action.
However, if the client doesn't care, it could simply provide the same exception handler for both input and output exceptions to the copy algorithm.
Here's how a generic method declaration for a copy algorithm could look like:
public <IE extends Exception, OE extends Exception>
copy( File src, ExceptionHandler<IOException, IE> inputHandler,
File dst, ExceptionHandler<IOException, OE> outputHandler)
throws IE, OE {
// ...
}
Note that the first type parameter for both handlers is an
IOException
for the cause exception.
The second type parameter determines the type of exception which may be
thrown by the exception handlers themselves and is freely selectable.
TODO: Consider allowing Throwable
as type parameters.
Modifier and Type | Method and Description |
---|---|
X |
fail(C cause)
Called to handle an exceptional condition which
does not
allow the caller to proceed its task.
|
void |
warn(C cause)
Called to handle an exceptional condition which
does
allow the caller to proceed its task.
|
X fail(C cause)
cause
- the exception to handle.void warn(C cause) throws X extends Exception
T
or return from the call.
If the implementation maintains a state, it must be updated
so that this instance can be reused to handle more exceptions.Copyright © 2005–2018 Schlichtherle IT Services. All rights reserved.