The JAX-RS framework provides javax.ws.rs.WebApplicationException which you can throw from the JAX-RS resource methods or provider implementations to report exceptions back to the caller. Later, in the request processing cycle, the default exception mapper class deployed by the JAX-RS runtime will intercept the exception thrown by the method and will generate an appropriate HTTP response object. WebApplicationException can be created by wrapping the response content, error text, or HTTP status code. As WebApplicationException is extended from RuntimeException, the methods that throw this exception do not need to have the throws clause for WebApplicationException in the method signature. When a method throws WebApplicationException, the server stops the execution of the request and sends the response created from WebApplicationException back to the client. Here is an example:

@DELETE 
@Path("departments/{id}") 
public void removeDepartment(@PathParam("id") Short id) { 
    //Read department from data store for id 
    Department department = findDepartmentEntity(id); 
    //throw exception if department to be deleted is not found 
    if(department == null){ 
        throw new  
            WebApplicationException(Response.Status.NOT_FOUND); 
    } 
    removeDepartmentEntity(department); 
} 

The preceding example throws WebApplicationException with the  HTTP status 404 Not Found if the department is not found in the data store. You can use different HTTP status codes, depending upon the use case. The javax.ws.rs.core.Response.Status class holds the commonly used status codes defined by HTTP. We discussed the HTTP status codes and their meaning in the HTTP status codes section in Chapter 1, Introducing the REST Architectural Style.

There are many exceptions available in JAX-RS, subclassed from javax.ws.rs.WebApplicationException. You can use the most appropriate one in your use case. Some of the exceptions extended from WebApplicationException are as follows: BadRequestException, ForbiddenException, NotAcceptableException, NotAllowedException, NotAuthorizedException, NotFoundException, NotSupportedException, RedirectionException, InternalServerErrorException, and ServiceUnavailableException.

You can also extend WebApplicationException to hold more meaningful error messages for your application, as shown in the following code:

import javax.ws.rs.WebApplicationException; 
import javax.ws.rs.core.MediaType; 
import javax.ws.rs.core.Response; 
 
public class DepartmentNotFoundWebAppException extends  
    WebApplicationException { 
 
    /** 
     * Generates a HTTP 404 (Not Found) exception. 
     */ 
    public DepartmentNotFoundWebAppException() { 
        super(Response.Status.NOT_FOUND); 
    } 
 
    /** 
     * Generates a HTTP 404 (Not Found) exception. 
     * @param message  
     */ 
    public DepartmentNotFoundWebAppException(String message) { 
        super(Response.status(Status.NOT_FOUND). 
        entity(message).type(MediaType.TEXT_PLAIN).build()); 
    } 
} 

WebApplicationException is subclassed from RuntimeException. This fits well for handling unexpected exceptions that may occur in the REST API implementation. However, for a typical business application, there may be many modules and certain modules may be reused in a non-REST context as well. So, you cannot live with WebApplicationException (which is automatically handled by the JAX-RS runtime) for all scenarios. The next section discusses the usage of the checked business exception in the JAX-RS application.