@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public interface ExceptionHandler<C extends Exception,E extends Exception>

A generic callback interface designed to be implemented by client applications in order to inject an exception handling strategy into a cooperative algorithm as its dependency. In the event of an exceptional condition, the cooperative algorithm would then call this interface (with an exception provided as the cause) in order to let the implementation decide how to proceed. The implementation would then make the following decisions:

1. If possible, shall the control be returned to the cooperative algorithm in order to proceed its task?
2. If not, shall the cause exception be wrapped in another exception before throwing it?

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:

• A source file cannot get opened because of insufficient access privileges.
• A destination file cannot get written because the file system is full.

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.