JAX-RS - Exception Mapping Provider

In JAX-RS the exception mapping providers map a checked or runtime exception to an instance of Response.

To provide exception mapping, we have to write a class which implements the ExceptionMapper<E extends Throwable> interface. This class may be annotated with @Provider for automatic discovery and registration.

To map an exception to a mapper, JAX-RS runtime implementation, selects the mapper whose generic type is the nearest superclass of the exception.

The ExceptionMapper interface

package javax.ws.rs.ext;

import javax.ws.rs.core.Response;

public interface ExceptionMapper<E extends Throwable> {

    Response toResponse(E exception);
}

Example

Implementing ExceptionMapper

@Provider
public class InvalidIdExceptionMapper
        implements ExceptionMapper<InvalidIdException> {


    @Override
    public Response toResponse(InvalidIdException exception) {
        return Response.status(Response.Status.NOT_FOUND)
                       .entity(prepareMessage(exception))
                       .type("text/plain")
                       .build();
    }

    private String prepareMessage(InvalidIdException exception) {

        String m = exception.getMessage();
        String r = "Invalid request.\n";
        r += String.format("Error Message: %s.%nError Type: %s.%n"
                        + "You may contact admin@example.com for more questions.",
                m, exception.getClass());
        return r;
    }
}

public class InvalidIdException extends RuntimeException {

    public InvalidIdException(String message) {
        super(message);
    }
}

Writing a JAX-RS resource

@Path("/employees")
public class EmployeeResource {

    @GET
    @Path("{id}")
    public String getEmployeeId(@PathParam("id") String employeeId) {
        return EmployeeService.Instance.getEmployeeById(employeeId);
    }
}

public enum EmployeeService {
    Instance;

    public String getEmployeeById(String id) {
        try {
            long l = Long.parseLong(id);
            //just a dummy response
            return "employee" + l;
        } catch (NumberFormatException e) {
            throw new InvalidIdException("Employee id is not valid, " + id);
        }

    }
}

mvn tomcat7:run-war

Output

Using HTTPie to access the resource:

Example Project

Dependencies and Technologies Used:

• jersey-server 2.25.1: Jersey core server implementation.
• jersey-container-servlet 2.25.1: Jersey core Servlet 3.x implementation.
• JDK 1.8
• Maven 3.3.9