49.3. JAX-RS 2.0 Exception Types
Overview
JAX-RS 2.0 introduces a number of specific HTTP exception types that you can throw (and catch) in your application code (in addition to the existing
WebApplicationException exception type). These exception types can be used to wrap standard HTTP status codes, either for HTTP client errors (HTTP 4xx status codes), or HTTP server errors (HTTP 5xx status codes).
Exception hierarchy
Figure 49.1, “JAX-RS 2.0 Application Exception Hierarchy” shows the hierarchy of application level exceptions supported in JAX-RS 2.0.
Figure 49.1. JAX-RS 2.0 Application Exception Hierarchy
WebApplicationException class
The
javax.ws.rs.WebApplicationException exception class (which has been available since JAX-RS 1.x) is at the base of the JAX-RS 2.0 exception hierarchy, and is described in detail in Section 49.2, “Using WebApplicationException exceptions to report errors”.
ClientErrorException class
The
javax.ws.rs.ClientErrorException exception class is used to encapsulate HTTP client errors (HTTP 4xx status codes). In your application code, you can throw this exception or one of its subclasses.
ServerErrorException class
The
javax.ws.rs.ServerErrorException exception class is used to encapsulate HTTP server errors (HTTP 5xx status codes). In your application code, you can throw this exception or one of its subclasses.
RedirectionException class
The
javax.ws.rs.RedirectionException exception class is used to encapsulate HTTP request redirection (HTTP 3xx status codes). The constructors of this class take a URI argument, which specifies the redirect location. The redirect URI is accessible through the getLocation() method. Normally, HTTP redirection is transparent on the client side.
Client exception subclasses
You can raise the following HTTP client exceptions (HTTP
4xx status codes) in a JAX-RS 2.0 application:
BadRequestException- Encapsulates the 400 Bad Request HTTP error status.
ForbiddenException- Encapsulates the 403 Forbidden HTTP error status.
NotAcceptableException- Encapsulates the 406 Not Acceptable HTTP error status.
NotAllowedException- Encapsulates the 405 Method Not Allowed HTTP error status.
NotAuthorizedException- Encapsulates the 401 Unauthorized HTTP error status. This exception could be raised in either of the following cases:
- The client did not send the required credentials (in a HTTP
Authorizationheader), or - The client presented the credentials, but the credentials were not valid.
NotFoundException- Encapsulates the 404 Not Found HTTP error status.
NotSupportedException- Encapsulates the 415 Unsupported Media Type HTTP error status.
Server exception subclasses
You can raise the following HTTP server exceptions (HTTP
5xx status codes) in a JAX-RS 2.0 application:
InternalServerErrorException- Encapsulates the 500 Internal Server Error HTTP error status.
ServiceUnavailableException- Encapsulates the 503 Service Unavailable HTTP error status.
