SeamFramework.orgCommunity Documentation
As an application developer (i.e., an end user of Catch), you'll be focused on writing exception handlers. An exception handler is a method on a CDI bean that is invoked to handle a specific type of exception. Within that method, you can implement any logic necessary to handle or respond to the exception.
Given that exception handler beans are CDI beans, they can make use of dependency injection, be scoped, have interceptors or decorators and any other functionality available to CDI beans.
Exception handler methods are designed to follow the syntax and semantics of CDI observers, with some special purpose exceptions explained in this guide. The advantage of this design is that exception handlers will be immediately familiar to you if you are studying or well-versed in CDI.
In this chapter, you'll learn how to define an exception handler and explore how and when it gets invoked. We'll
begin by covering the two annotations that are used to declare an exception handler,
@HandlesExceptions
and @Handles
.
Exception handlers are contained within exception handler beans, which are CDI beans annotated with
@HandlesExceptions
. Exception handlers are methods whose first parameter is an instance of
CaughtException<T extends Throwable>
annotated with the @Handles
annotation.
The @HandlesException
annotation is simply a marker annotation that instructs the Seam
Catch CDI extension to scan the bean for handler methods.
Let's designate a CDI bean as an exception handler by annotating it with
@HandlesException
.
@HandlesExceptions
public class MyHandlers {}
That's all there is to it. Now we can begin defining exception handling methods on this bean.
@HandlesExceptions
annotation may be deprecated in favor of annotation indexing
done by Seam Solder.
@Handles
is a method parameter annotation that designates a method as an exception
handler. Exception handler methods are registered on beans annotated with
@HandlesExceptions
. Catch will discover all such methods at deployment time.
Let's look at an example. The following method is invoked for every exception that Catch processes and
prints the exception message to stout. (Throwable
is the base exception type in Java and
thus represents all exceptions).
@HandlesExceptions
public class MyHandlers
{void printExceptions(@Handles CaughtException<Throwable> evt)
{
System.out.println("Something bad happened: " +evt.getException().getMessage());
evt.proceed();
}
}
The | |
The | |
The | |
This handler does not modify the invocation of subsequent handlers, as designated by invoking
proceed() on CaughtException . As this is the default behavior,
this line could be omitted.
|
The @Handles
annotation must be placed on the first parameter of the method, which must
be of type CaughtException<T extends Throwable>
. Handler methods are similar to CDI
observers and, as such, follow the same principals and guidelines as observers (such as invocation,
injection of parameters, qualifiers, etc) with the following exceptions:
CaughtException
In addition to designating a method as exception handler, the @Handles
annotation
specifies two pieces of information about when the method should be invoked relative to other handler
methods:
TraversalPath.ASCENDING
.
Let's take a look at more sophisticated example that uses all the features of handlers to log all exceptions.
@HandlesExceptions
public class MyHandlers
{void logExceptions(@Handles(during = TraversalPath.DESCENDING)
@WebRequest CaughtException<Throwable> evt,
Logger log)
{
log.warn("Something bad happened: " + evt.getException().getMessage());
}
}
The | |
This handler has a default precedence of 0 (the default value of the precedence attribute on
| |
This handler is qualified with | |
Any additional parameters of a handler method are treated as injection points. These parameters are
injected into the handler when it is invoked by Catch. In this case, we are injecting a
|
A handler is guaranteed to only be invoked once per exception (automatically muted), unless it reenables
itself by invoking the unMute()
method on the CaughtException
instance.
Handlers must not throw checked exceptions, and should avoid throwing unchecked exceptions.
When an exception is thrown, chances are it's nested (wrapped) inside other exceptions. (If you've ever examined a server log, you'll appreciate this fact). The collection of exceptions in its entirety is termed an exception stack trace.
The outermost exception of an exception stack trace (e.g., EJBException, ServletException, etc) is probably of little use to exception handlers. That's why Catch doesn't simply pass the exception stack trace directly to the exception handlers. Instead, it intelligently unwraps the stack trace and treats the root exception cause as the primary exception.
The first exception handlers to be invoked by Catch are those that match the type of root cause. Thus, instead
of seeing a vague EJBException
, your handlers will instead see an meaningful exception such
as ConstraintViolationException
. This feature, alone, makes Catch a worthwhile
tool.
Catch continues to work through the exception stack trace, notifying handlers of each exception in the stack,
until a handler flags the exception as handled. Once an exception is marked as handled, Catch stops processing
the exception. If a handler instructed Catch to rethrow the exception (by invoking
CaughtException#rethrow()
, Catch will rethrow the exception outside the Catch
infrastructure. Otherwise, it simply returns flow control to the caller.
Consider a stack trace containing the following nested causes (from outer cause to root cause):
Catch will unwrap this exception and notify handlers in the following order:
If there's a handler for PersistenceException
, it will likely prevent the handlers for
EJBException
from being invoked, which is a good thing since what useful information can
really be obtained from EJBException
?
While processing one of the causes in the exception stack trace, Catch has a specific order it uses to invoke the handlers, operating on two axes:
We'll first address the traversal of the exception type hierarchy, then cover relative handler precedence.
Catch doesn't simply invoke handlers that match the exact type of the exception. Instead, it walks up and down the type hierarchy of the exception. It first notifies least specific handler, then gradually works down the type hiearchy towards handlers for the actual exception type. It then walks back up again towards the least specific handler.
There are two phases of this traversal:
By default, handlers are registered into the ascending traversal path. That means in most cases, Catch starts with handlers of the actual exception type and works up towards the handler for the least specific type.
However, when a handler is registered to be notified during the descending traversal, as in the example above, Catch will notify that exception handler before the exception handler for the actual type is notified.
Let's consider an example. Assume that Catch is handling the SocketException
. It will
notify handlers in the following order:
Throwable
Exception
IOException
SocketException
IOException
Exception
Throwable
The same type traversal occurs for each exception processed in the stack trace.
In order for a handler to be notified of the IOException
before the
SocketException
, it would have to specify the descending traversal path explicitly:
void handleIOException(@Handles(during = TraversalPath.DESCENDING)
CaughtException<IOException> evt)
{
System.out.println("An I/O exception occurred, but not sure what type yet");
}
Descending handlers are typically used for logging exceptions because they are not likely to be short-circuited (and thus always get invoked).
When Catch finds more than one handler for the same exception type, it orders the handlers by precendence. Handlers with higher precendence are executed before handlers with a lower precedence. If Catch detects two handlers for the same type with the same precedence, it detects it as an error and throws an exception at deployment time.
Let's define two handlers with different precendence:
void handleIOExceptionFirst(@Handles(precendence = 100) CaughtException<IOException> evt)
{
System.out.println("Invoked first");
}
void handleIOExceptionSecond(@Handles CaughtException<IOException> evt)
{
System.out.println("Invoked second");
}
The first method is invoked first since it has a higher precendence (100) than the second method, which has the default precedence (0).
To make specifying precendence values more convenience, Catch provides several built-in constants, available
on the Precedence
interface:
To summarize, here's how Catch determines the order of handlers to invoke (until a handler marks exception as handled):
There are two APIs provided by Catch that should be familiar to application developers:
CaughtException
ExceptionStack
In addition to providing information about the exception being handled, the
CaughtException
object contains methods to control the exception handling process, such
as rethrowing the exception, aborting the handler chain or unmuting the current handler.
Five methods exist on the CaughtException
object to give flow control to the handler
abort()
- terminate all handling immediately after this handler, does not mark the
exception as handled, does not re-throw the exception.
rethrow()
- continues through all handlers, but once all handlers have been called
(assuming another handler does not call abort() or handled()) the initial exception passed to Catch is
rethrown. Does not mark the exception as handled.
handled()
- marks the exception as handled and terminates further handling.
proceed()
- default. Marks the exception as handled and proceeds with the rest of the
handlers.
proceedToCause()
- marks the exception as handled, but proceeds to the next cause in
the cause container, without calling other handlers for the current cause.
Once a handler is invoked it is muted, meaning it will not be run again for that exception stack trace,
unless it's explicitly marked as unmuted via the unmute()
method on
CaughtException
.
ExceptionStack
contains information about the exception causes relative to the current
exception cause. It is accessed by calling the method getCauses()
on the
CaughtException
object. Please see API
docs for more information, all methods are fairly self-explanatory.