Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - RESTful services > Plan JAX-RS web applications

Define exception mappers for resource exceptions and errors

Java API for RESTful Web Services (JAX-RS) applications can produce exceptions and errors. The default behavior is to use the exception handling functionality of application container such as JSP error pages. However, you can customize the error handling and send specific responses back when an exception or error occurs.

JAX-RS resource methods, like any Java method, can throw checked and unchecked exceptions. By default, an unchecked runtime exception or error occurs in the container again. A checked exception is wrapped in a ServletException for resources running in the web container. Therefore, a developer can use error handling facilities such as JSP error pages to handle exceptions thrown from a JAX-RS application.

JAX-RS introduced the exception, javax.ws.rs.WebApplicationException. A developer can specify a specific error class name or javax.ws.rs.core.Response object when creating a WebApplicationException. When the WebApplicationException is thrown, the information included in the exception by way of a status class name or Response object is used to serialize a response.

If you cannot throw the exception, WebApplicationException, in your code and you cannot use the error handling facilities in the web container, but to use a custom error response, then you can create a customized JAX-RS javax.ws.rs.ext.ExceptionMapper class to map exceptions to HTTP error responses.

The following procedure illustrates how to write a custom ExceptionMapper class.

Procedure

1. Create a class that implements the javax.ws.rs.ext.ExceptionMapper class and annotate the class with the javax.ws.rs.ext.Provider annotation. This step assumes that your JAX-RS resource can throw the exception, MyCustomException, in its methods. The following example illustrates a simple ExceptionMapper class:

   import javax.ws.rs.core.Response;
   import javax.ws.rs.ext.ExceptionMapper;
   import javax.ws.rs.ext.Provider;
   
   @Provider
   public class CustomExceptionMapper implements ExceptionMapper
   <MyCustomException> {
   
       public Response toResponse(MyCustomException exception) {
           return null;
       }
   
   }
   

2. In the toResponse(MyCustomException) method, return a Response object that contains the customized error response. The following example illustrates a customized ExceptionMapper.toResponse(MyCustomException) method:

   @Provider
   public class CustomExceptionMapper implements ExceptionMapper
   <MyCustomException> {
   
       public Response toResponse(MyCustomException exception) {
           return Response.status(500).entity("Unfortunately, the application cannot
               process your request at this time.").type("text/plain").build();
       }
   
   }
   

   We can have additional code where you log an error, inspect the exception thrown, or use more complex logic.
3. Package the compiled custom ExceptionMapper class with your web application project. If you rely on the annotation scanning capabilities to find all of your JAX-RS classes in your web application, no additional steps are required. However, if you return all of the relevant JAX-RS resource classes and providers in a JAX-RS application subclass method, then also add the custom ExceptionMapper class to the returned set. The following example illustrates a preexisting javax.ws.rs.core.Application subclass:

   import java.util.HashSet;
   import java.util.Set;
   
   import javax.ws.rs.core.Application;
   
   public class MyApplication extends Application {
   
       @Override
       public Set
   <Class
   <?>> getClasses() {
           Set
   <Class
   <?>> classes = new HashSet
   <Class
   <?>>();
           classes.add(CustomExceptionMapper.class);
           /* add your additional JAX-RS classes here */
           return classes;
       }
   }
   

   When exceptions occur in your JAX-RS resource methods, you can customize the HTTP error response so that a user cannot see a stack trace or potentially confidential data. Use an ExceptionMapper or the exception handling functionality in the web container to give more helpful responses if the application is not behaving correctly.

Results

You have written a custom ExceptionMapper to handle exceptions in your JAX-RS web application.
Configure JAX-RS applications using JAX-RS 1.1 methods

+

Search Tips   |   Advanced Search