SeamFramework.orgCommunity Documentation

Chapter 2. Exception Handling

2.1. Seam Catch Integration
2.2. Declarative Exception Mapping
2.2.1. Annotation-based configuration
2.2.2. XML configuration
2.2.3. Declarative exception mapping processing

The JAX-RS specification defines the mechanism for exception mapping providers as the standard mechanism for Java exception handling. The Seam REST module comes with an alternative approach, which is more consistent with the CDI programming model. It is also easier to use and still remains portable.

The Seam REST module allows you to:

Seam Catch handles exceptions within the Seam REST module: as result, an exception that occurs during an invocation of a JAX-RS service is routed through the Catch exception handling mechanism similar to the CDI event bus. This allows you to implement the exception handling logic in a loosely-coupled fashion.

The following code sample demonstrates a simple exception handler that converts the NoResultException exception to a 404 HTTP response.


Similarly to the CDI event bus, exceptions handled by a handler method can be filtered by qualifiers. The example above treats only exceptions that occur in a JAX-RS service invocation (as opposed to all exceptions of the given type that occur in the application, for example in the view layer). Thus, the @RestRequest qualifier is used to enable the handler only for exceptions that occur during JAX-RS service invocation.

Catch integration is optional and only enabled when Catch libraries are available on classpath. For more information on Seam Catch, refer to Seam Catch reference documentation .

Exception-mapping rules are often fairly simple. Thus, instead of being implemented programmatically, they can be expressed declaratively through metadata such as Java annotations or XML. The Seam REST module supports both ways of declarative configurations.

For each exception type, you can specify a status code and an error message of the HTTP response.

You can configure Seam REST exception mapping directly in your Java code with Java Annotations. An exception mapping rule is defined as a @ExceptionMapping annotation. Use an @ExceptionMapping.List annotation to define multiple exception mappings.


The @ExceptionMapping annotation can be applied on any Java class in the deployment. However, it is recommended to keep all exception mapping declarations in the same place, for example, in the javax.ws.rs.core.Application subclass.


As an alternative to the annotation-based configuration, you can use the Seam Config module to configure the SeamRestConfiguration class in XML.

First, add the Seam Config module to the application. If you are using maven, you can do this by specifying the following dependency:


For more information on the Seam Config module, refer to the Seam Config reference documentation . Once you have added the Seam XML module, specify the configuration in the seam-beans.xml file, located in the WEB-INF or META-INF folder of the web archive.


Furthermore, you can use EL expressions in message templates to provide dynamic and more descriptive error messages.