SeamFramework.orgCommunity Documentation

Chapter 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

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.

Adding a handler is simply creating a class and a method the follows the above rules (class annotated with @HandlesExceptions and a method with the first parameter being a CaughtException and annotated with@Handles). Catch will discover all handler methods at deploy time. See the example above for a simple, but complete handler.

The ordering of handlers is multifaceted. Based on the traversal path of the causing container handlers are ordered according to the hiearchy of the excption type (most specific first if TraversalPath.ASCENDING, least specific first if TraversalPath.DESCENDING traversal), and the precedence when two handlers are for the same exception type.

The precedence of a handler helps determine the order of the handler relative to other handlers of the same exception type. It follows a high-to-low integer schema (the higher the precedence, the sooner the handler is invoked during traversal of the causing chain).

When an exception is handled with Catch the causing container is unwrapped to get at each exception. The first pass (TraversalPath.DESCENDING) starts with the outer most exception working it's way to the root exception. The traversal is then reversed and traversed from root cause up. This allows handlers to take part in various stages of the causing container. At each entry in the container, handlers are invoked based on the exception type (either an exact match or a super type) of the entry. For example if the exception type isSocketException, handlers for types SocketException, IOException, Exception and Throwable would all invoked (in that order), however, a handler for BindException would not be invoked.

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