Exception mapping provider

Implement an exception mapping provider when customizing mapping between the exceptions that can be processed by the exception mapping provider and the HTTP responses.

Implements the ExceptionMapper<T> interface for the exception mapping provider and annotate the interface with the Provider annotation.

An example of the exception mapping provider is as follows.

package com.sample.providers;
 
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;
 
//exception mapping provider to customize the mapping of the RuntimeException to the HTTP response
@Provider
public class RuntimeExceptionMapper implements
    ExceptionMapper<RuntimeException> {
 
  public Response toResponse(RuntimeException runtimeException) {
    int httpStatus = 0;
    String entity = "";
    
    //Use the ResponseBuilder class to create the HTTP response 
    return Response.status(httpStatus).entity(entity).build();
  }
}

In this example, the provider com.sample.providers.RuntimeExceptionMapper is the exception mapping provider. The ExceptionMapper interface with RuntimeException specified in the type parameter is implemented. Here, the HTTP response is created by calling the toResponse method of the ResponseBuilder class.

Note that only one exception mapping provider can be created for one exception. If two or more exception mapping providers are created for one exception, the (KDJJ10028-E, KDJJ10039-E) errors occur and the exception mapping provider is not instantiated. The system returns 500 as the HTTP status code.

Organization of this subsection: (1) Constructor; (2) Fields and bean properties

(1) Constructor

The exception mapping provider must contain at least one public constructor including the default public constructor (a constructor that is not explicitly declared).

If no public constructor is declared, the (KDJJ10002-E, KDJJ10006-E) errors occur and the exception mapping provider is not instantiated. The system returns 500 as the HTTP status code.

The following constructors are not public constructors:

private constructor
protected constructor
A constructor without an access identifier

For constructor parameters, you can use the Context annotation as an injection annotation. If an injection annotation other than the Context annotation is used, the (KDJJ10006-E) error occurs and the exception mapping provider is not instantiated. The system returns 500 as the HTTP status code. The following injection annotations cannot be used:

MatrixParam
QueryParam
PathParam
CookieParam
HeaderParam
FormParam

If you specify an annotation other than an injection annotation for these parameters, the (KDJJ10006-E) error message is output and the system returns 500 as the HTTP status code.

If the exception mapping provider contains one or more public constructors with parameters, the JAX-RS engine uses the constructor with maximum parameters to instantiate the exception mapping provider. When there are two or more constructors with maximum parameters, the JAX-RS engine uses the initially defined constructor to instantiate the exception mapping provider. In such cases, the warning message (KDJJ20011-W) is output to the log.

If a system throws a runtime exception when the exception mapping provider is instantiated, the (KDJJ10028-E, KDJJ10039-E) errors occur and 500 is returned as the HTTP status code.

(2) Fields and bean properties

You can use Context annotation as the injection annotation for the fields and bean properties of the exception mapping provider.

If you use an injection annotation other than the Context annotation, that annotation is ignored. You cannot use the following annotations.

MatrixParam
QueryParam
PathParam
CookieParam
HeaderParam
FormParam

17.2.2 Exception mapping provider

(1) Constructor

(2) Fields and bean properties