SeamFramework.orgCommunity Documentation

Chapter 57. Exception Handling

57.1. Solder Exception Handling Integration
57.2. Declarative Exception Mapping
57.2.1. Annotation-based configuration
57.2.2. XML configuration
57.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:

Solder exception handling framework 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 Solder 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.

For more information on Solder exception handling, refer to Solder 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 configuration facilities provided by Solder to configure the SeamRestConfiguration class in XML.

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


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