SeamFramework.orgCommunity Documentation

Seam Catch


1. Seam Catch Introduction
2. Installation
3. Usage
3.1. Annotations
3.1.1. @HandlesExceptions
3.1.2. @Handles
3.2. Adding Handlers
3.3. Ordering of Handlers
3.4. Traversal of the causing container
3.5. API Objects
3.5.1. CaughtException
3.5.2. ExceptionStack
4. Framework Integration
4.1. Creating and Firing an ExceptionToCatchEvent
4.2. Default Handlers and Qualifiers
4.2.1. Default Handlers
4.2.2. Qualifiers
4.3. Supporting ServiceHandlers

The Seam Catch module creates a simple, yet robust base for other modules and users to create a custom and complete exception handling process. Exception handling is done using CDI events, keeping exception handling noninvasive and also helping the program or module to stay minimally coupled to the exception handling framework.

The Seam Catch API is the only compile time dependency a project needs, and an implementation must also be included, either explicitly or via some other module depending on it (and exposing their own specialized extensions) is all that is needed during runtime. If you are using Maven as your build tool, you can add the following dependency to your pom.xml file:



      <dependency>
         <groupId>org.jboss.seam.catch</groupId>
         <artifactId>seam-catch-api</artifactId>
         <version>${seam-catch-version}</version>
         <scope>compile</scope>
      </dependency>

      <dependency>
         <groupId>org.jboss.seam.catch</groupId>
         <artifactId>seam-catch-impl</artifactId>
         <version>${seam-catch-version}</version>
         <scope>runtime</scope>
      </dependency>
   

Note

The runtime dependency is only needed if another Seam 3 module being used doesn't already use it. Typically this will only be for Java SE development.

Tip

Replace ${seam-catch-version} with the most recent or appropriate version of Seam Catch.

An end user of the Seam Catch Framework is typically only concerned with Exception Handlers (methods in Handler Beans, which are similar to CDI Observers). Handler Beans are CDI beans with the @HandlesExceptions annotation. There may be other resources made available by other modules which can be injected into handler methods on an as needed basis. For further information, please check the API docs, or examples.

There are other objects used in Catch that should be familiar to handler writers namely

Integration of Seam Catch with other frameworks consists of one main step, and two other optional (but highly encouraged) step:

  • creating and firing an ExceptionToCatchEvent
  • adding any default handlers and qualifiers with annotation literals (optional)
  • supporting ServiceHandlers for creating exception handlers

ServiceHandlers make for a very easy and concise way to define exception handlers take the following example comes from the jaxrs example in the distribution:

@HandlesExceptions

@ExceptionResponseService
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 Catch integration, however, there may be situtations where ServiceHandlers simply do not make sense.

Note

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()).