SeamFramework.orgCommunity Documentation

Chapter 27. Exception Handling - Framework Integration

27.1. Creating and Firing an ExceptionToCatch event
27.2. Default Handlers and Qualifiers
27.2.1. Default Handlers
27.2.2. Qualifiers
27.3. Supporting ServiceHandlers
27.4. Programmatic Handler Registration

Integration of Solder's exception handling with other frameworks consists of one main step, and two other optional (but highly encouraged) steps:

An ExceptionToCatch is constructed by passing a Throwable and optionally qualifiers for handlers. Firing the event is done via CDI events (either straight from the BeanManager or injecting a Event<ExceptionToCatch> and calling fire).

To ease the burden on the application developers, the integration should tie into the exception handling mechanism of the integrating framework, if any exist. By tying into the framework's exception handling, any uncaught exceptions should be routed through Solder's exception handling system and allow handlers to be invoked. This is the typical way of using Solder to handle exceptions. Of course, it doesn't stop the application developer from firing their own ExceptionToCatch within a catch block.

ServiceHandlers make for a very easy and concise way to define exception handlers. The following example is a possible usage of ServiceHandlers within a JAX-RS application:


public interface DeclarativeRestExceptionHandlers
   @SendHttpResponse(status = 403, message = "Access to resource denied (Annotation-configured response)")
   void onNoAccess(@Handles @RestRequest CaughtException<AccessControlException> e);
   @SendHttpResponse(status = 400, message = "Invalid identifier (Annotation-configured response)")
   void onInvalidIdentifier(@Handles @RestRequest CaughtException<IllegalArgumentException> e);

All the vital information that would normally be done in the handler method is actually contained in the @SendHttpResponse annotation. The only thing left is some boiler plate code to setup the Response. In a jax-rs application (or even in any web application) this approach helps developers cut down on the amount of boiler plate code they have to write in their own handlers and should be implemented in any Solder integration, however, there may be situations where ServiceHandlers simply do not make sense.


If ServiceHandlers are implemented make sure to document if any of the methods are called from CaughtException, specifically abort(), handled() or rethrow(). These methods affect invocation of other handlers (or rethrowing the exception in the case of rethrow()).

Handlers can be registered programatically at runtime instead of solely at deploy time. This done very simply by injecting HandlerMethodContainer and calling registerHandlerMethod(HandlerMethod).

HandlerMethod has been relaxed in this version as well, and is not tied directly to Java. It is therefore feasible handlers written using other JVM based languages could be easily registered and participate in exception handling.