Chapter 2. Declarative Exception Mapping

2.1. Programmatic configuration
2.2. XML configuration
2.3. Exception Mapping

The JAX-RS specification comes with Exception Mapping Providers as a standard mechanism for treating Java exceptions. This approach works fine for complex cases, however, the exception handling logic is often trivial and not worth implementing Exception Mapper Providers for each exception type. In these situations, declarative approach is more appropriate. The Seam REST module allows exception types to be bound to HTTP responses declaratively.

For each exception type, it is possible to specify the status code and the error message of the HTTP response. There are two ways of exception mapping configuration in Seam REST.

2.1. Programmatic configuration

Seam REST exception mapping can be configured from Java code. Firstly, create an ExceptionMappingConfiguration subclass which @Specializes the provided one. Then, implement a @PostConstruct-annotated method in which the ExceptionMapping definitions are added as shown in the following example.

Example 2.1. Programmatic exception mapping configuration

@Specializes

public class CustomExceptionMappingConfiguration extends ExceptionMappingConfiguration {

{

    @PostConstruct

    public void setup()

    {

        addExceptionMapping(new ExceptionMapping(NoResultException.class, 404, "Requested resource does not exist."));

        addExceptionMapping(new ExceptionMapping(IllegalArgumentException.class, 400, "Illegal parameter value."));

    }

}

When the NoResultException is thrown at runtime, the client receives the following HTTP response.

Table 2.1. ExceptionMapping properties

Name	Required	Default value	Description
exceptionType	true	-	Fully-qualified class name of the exception class
statusCode	true	-	HTTP status code
message	false	-	Error message sent within the HTTP response
interpolateMessageBody	false	true	Enables/Disables EL interpolation of the error message

2.2. XML configuration

An alternative and more practical way of configuration is to use the Seam XML module to configure the ExceptionMappingConfiguration and ExceptionMapping classes in XML.

Firstly, the Seam XML module needs to be added to the application. If using maven, this can be done by specifying the following dependency:

Example 2.2. Seam XML dependency added to the pom.xml file.


<dependency> 

    <groupId>org.jboss.seam.xml</groupId> 

    <artifactId>seam-xml-config</artifactId> 

    <version>${seam.xml.version}</version> 

</dependency>

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

Example 2.3. Exception mapping configuration in seam-beans.xml


<rest:ExceptionMappingConfiguration>

    <s:replaces/>

    <rest:exceptionMappings>

        <s:value>

            <rest:ExceptionMapping exceptionType="javax.persistence.NoResultException" statusCode="404">

                <rest:message>Requested resource does not exist.</rest:message>

            </rest:ExceptionMapping>

        </s:value>

        <s:value>

            <rest:ExceptionMapping exceptionType="java.lang.IllegalArgumentException" statusCode="400">

                <rest:message>Illegal parameter value.</rest:message>

            </rest:ExceptionMapping>

        </s:value>

    </rest:exceptionMappings>

</rest:ExceptionMappingConfiguration>

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

Example 2.4. Exception mapping configuration in seam-beans.xml


<rest:ExceptionMapping exceptionType="javax.persistence.NoResultException" statusCode="404">

    <rest:message>Requested resource with id #{pathParameters['id']} does not exist.</rest:message>

</rest:ExceptionMapping>

2.3. Exception Mapping

When an exception occurs at runtime, the SeamExceptionMapper first looks for a matching ExceptionMapping. If it finds one, it creates an HTTP response with the specified status code and error message.

The error message is marshalled within a JAXB object. As a result, the error message is available in multiple media formats. The most commonly used formats are XML and JSON. Most JAX-RS implementations provide media providers for both of these formats. In addition, the error message is also available in plain text.

Example 2.5. Sample HTTP response


HTTP/1.1 404 Not Found

Content-Type: application/xml

Content-Length: 123

        

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<error>

    <message>Requested resource does not exist.</message>

</error>