Exception Handling

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Mon, 31 Mar 2008 12:07:18 -0400

Issue 26[1] concerns exception handling. Currently the only exception
handled by a JAX-RS runtime is our own WebApplicationException, any
RuntimeException is propagated to the container, and we don't say what
should happen if a resource method declares checked exceptions (see
ednote 3.1 in the latest spec draft). Here's a proposal for addressing

(i) Allow resource methods to declare checked exceptions

(ii) Define a new provider type along the following lines:

public interface ExceptionMapper<E extends Exception> {

   boolean isMappable(Class<E> type); // not sure if we really need this

   Response map(E exception);

An application can define implementations of this interface to convert
any runtime or checked exception to a Response that will then be
processed in the usual way. Implementations will catch all exceptions
and look for a provider that will handle the exception. If one is
found it is used to create a response, if not the implementation
rethrows the exception, see (iv).

(iii) Define provider ordering such that the closest matching
exception mapper (by inheritance hierarchy) is used. Thus if an
application provides ExceptionMapper<Exception> and
ExceptionMapper<RuntimeException> and the application throws
IndexOutOfBoundsException then the implementation of
ExceptionMapper<RuntimeException> will be used.

(iv) Define a new RuntimeException: ContainerException. An application
can throw this exception directly to have the exception propagate to
the container. An implementation will use this to wrap checked
exceptions thrown by a resource method and not handled by an exception
mapper provider. Runtime exceptions not handled by an exception mapper
provider will be rethrown directly.

(v) Define deviations to (iv) for servlet container. An servlet-based
implementation won't wrap ServletException or IOException since these
can be thrown directly.

Thoughts, comments ?


Marc Hadley <marc.hadley at>
CTO Office, Sun Microsystems.