Chapter 24. Exception Handling
24.1. Exception Mappers
ExceptionMapper
s are custom, application-provided components that can catch application exceptions and write specific HTTP responses. They are associated with @Provider
, and implement the following 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 throws an exception, the exception is caught by the JAX-RS runtime. JAX-RS then scans registered
ExceptionMapper
s to locate one which supports marshalling the exception type thrown. An example ExceptionMapper
follows:
@Provider public class EJBExceptionMapper implements ExceptionMapper<javax.ejb.EJBException> { Response toResponse(EJBException exception) { return Response.status(500).build(); } }
ExceptionMapper
s are registered in the same way as MessageBodyReader
s and MessageBodyWriter
s: by scanning through the RESTEasy provider context-param
(if you are deploying in a WAR
file), or programmatically through the ResteasyProviderFactory
class.