JBoss.orgCommunity Documentation
ExceptionMappers are custom, application provided, components that can catch thrown application exceptions and write specific HTTP responses. The are classes annotated with @Provider and that implement this interface
package javax.ws.rs.ext; import javax.ws.rs.core.Response; /** * Contract for a provider that maps Java exceptions to * {@link javax.ws.rs.core.Response}. An implementation of this interface must * be annotated with {@link Provider}. * * @see Provider * @see javax.ws.rs.core.Response */ public interface ExceptionMapper<E> { /** * Map an exception to a {@link javax.ws.rs.core.Response}. * * @param exception the exception to map to a response * @return a response mapped from the supplied exception */ Response toResponse(E exception); }
When an application exception is thrown it will be caught by the JAX-RS runtime. JAX-RS will then scan registered ExceptionMappers to see which one support marshalling the exception type thrown. Here is an example of ExceptionMapper
@Provider public class EJBExceptionMapper implements ExceptionMapper<javax.ejb.EJBException> { Response toResponse(EJBException exception) { return Response.status(500).build(); } }
You register ExceptionMappers the same way you do MessageBodyReader/Writers. By scanning, through the resteasy provider context-param (if you're deploying via a WAR file), or programmatically through the ResteasyProviderFactory class.
Resteasy has a set of built-in exceptions that are thrown by it when it encounters errors during dispatching or marshalling. They all revolve around specific HTTP error codes. You can find them in RESTEasy's javadoc under the package org.jboss.resteasy.spi. Here's a list of them:
Table 25.1.
Exception | HTTP Code | Description |
---|---|---|
BadRequestException | 400 | Bad Request. Request wasn't formatted correctly or problem processing request input. |
UnauthorizedException | 401 | Unauthorized. Security exception thrown if you're using Resteasy's simple annotation-based role-based security |
InternalServerErrorException | 500 | Internal Server Error. |
MethodNotAllowedException | 405 | Method Not Allowed. There is no JAX-RS method for the resource that can handle the invoked HTTP operation. |
NotAcceptableException | 406 | Not Acceptable. There is no JAX-RS method that can produce the media types listed in the Accept header. |
NotFoundException | 404 | Not Found. There is no JAX-RS method that serves the request path/resource. |
Failure | N/A | Internal Resteasy. Not logged |
LoggableFailure | N/A | Internal Resteasy error. Logged |
DefaultOptionsMethodException | N/A | If the user invokes HTTP OPTIONS and no JAX-RS method for it, Resteasy provides a default behavior by throwing this exception |