The JAX-RS API introduced the WebApplicationException runtime exception
to provide an easy way for resource methods to create exceptions that are appropriate for RESTful
clients to consume. WebApplicationException exceptions can include a
Response object that defines the entity body to return to the originator of the
request. It also provides a mechanism for specifying the HTTP status code to be returned to the client
if no entity body is provided.
The easiest means of creating a WebApplicaitonException exception
is to use either the no argument constructor or the constructor that wraps the original exception in
a WebApplicationException exception. Both constructors create a
WebApplicaitonException with an empty response.
When an exception created by either of these constructors is thrown, the runtime returns
a response with an empty entity body and a status code of 500 Server Error.
When you want to return an error code other than 500, you can use one of the
four WebApplicaitonException constructors that allow you to specify
the status. Two of these constructors, shown in Example 5.1, take the
return status as an integer.
Example 5.1. Creating a WebApplicationException with a status code
WebApplicationException(int status);WebApplicationException(java.lang.Throwable cause,
int status);The other two, shown in Example 5.2 take the response status as an
instance of Response.Status.
Example 5.2. Creating a WebApplicationException with a status code
WebApplicationException(javax.ws.rs.core.Response.Status status);WebApplicationException(java.lang.Throwable cause,
javax.ws.rs.core.Response.Status status);When an exception created by either of these constructors is thrown, the runtime returns a response with an empty entity body and the specified status code.
If you want a message to be sent along with the exception, you can use one of the
WebApplicationException constructors that takes a
Response object. The runtime uses the Response
object to create the response sent to the client. The entity stored in the response is mapped to the
entity body of the message and the status field of the response is mapped to the HTTP status of the
message.
Example 5.3 shows code for returning a text message to a
client containing the reason for the exception and sets the HTTP message status to
409 Conflict.
Example 5.3. Sending a message with an exception
import javax.ws.rs.core.Response;
import javax.ws.rs.WebApplicationException;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;
...
ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(Response.Status.CONFLICT);
builder.entity("The requested resource is conflicted.");
Response response = builder.build();
throw WebApplicationException(response);It is possible to extend the WebApplicationException
exception. This would allow you to create custom exceptions and eliminate some boiler
plate code.
Example 5.4 shows a new exception that creates a similar response to the code in Example 5.3.
Example 5.4. Extending WebApplicationException
public class ConflicteddException extends WebApplicationException
{
public ConflictedException(String message)
{
ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(Response.Status.CONFLICT);
builder.entity(message);
super(builder.build());
}
}
...
throw ConflictedException("The requested resource is conflicted."); |  |  |
 |
