Java Reference
In-Depth Information
not a JAX-RS method with an
@Produces
annotation that is compatible with the client's
Ac-
cept
header.
NotSupportedException
is used when a client is posting a representation that the server
does not understand. The JAX-RS runtime will automatically throw this exception if there is
no JAX-RS method with an
@Consumes
annotation that matches the
Content-Type
of the
posted entity.
InternalServerErrorException
is a general-purpose error that is thrown by the server.
For applications, you would throw this exception if you've reached an error condition that
doesn't really fit with the other HTTP error codes. The JAX-RS runtime throws this excep-
tion if a
MessageBodyWriter
fails or if there is an exception thrown from an
Excep-
tionMapper
.
ServiceUnavailableException
is used when the server is temporarily unavailable or busy.
In most cases, it is OK for the client to retry the request at a later time. The HTTP 503 status
code is often sent with a
Retry-After
header. This header is a suggestion to the client when
it might be OK to retry the request. Its value is in seconds or a formatted date string.
Ser-
viceUnavailableException
has a few convenience constructors to help with initializing
this header:
public
public
ServiceUnavailableException
(
Long retryAfter
) {}
public
public
ServiceUnavailableException
(
Date retryAfter
) {}
Mapping default exceptions
What's interesting about the default error handling for JAX-RS is that you can write an
Ex-
ceptionMapper
for these scenarios. For example, if you want to send back a different re-
sponse to the client when JAX-RS cannot find an
@Produces
match for an
Accept
header,
you can write an
ExceptionMapper
for
NotAcceptableException
. This gives you complete
control on how errors are handled by your application.
Wrapping Up
In this chapter, you learned that JAX-RS has default response codes for both success and er-
ror conditions. For more complex responses, your JAX-RS resource methods can return
javax.ws.rs.core.Response
objects. JAX-RS has a few exception utilities. You can throw
instances of
javax.ws.rs.WebApplicationException
or let the underlying servlet contain-
er handle the exception. Or, you can write an
ExceptionMapper
that can map a particular ex-
ception to an HTTP response.
Chapter 22
walks you through some sample code that you can
use to test-drive many of the concepts and APIs introduced in this chapter.
