(Quick Reference)
4 Handling Responses - Reference Documentation
Authors: Bud Byrd
Version: 2.0.2
4 Handling Responses
The
Jersey Request Builder attempts to provide as much convenience around HTTP responses as it can, while providing options that provide direct access to the underlying objects returned from Jersey-Client.
4.1 Automatic Conversion
When the response to a request is received with a successful HTTP status code, by default, the response body will be converted if possible and returned from the request method.
These are the steps followed to determine what to return:
- If
rawClientResponse
is true
, return the Jersey-Client ClientResponse
object.
- If
binaryResponse
is true
, return the response as a byte
array.
- If a
Content-Type
header that is JSON compatible is received and convertJson
is true
, convert the response to a List
or Map
(or null
if the response was empty) and return it.
- If a
Content-Type
header that is XML compatible is received and convertXML
is true
, convert the response using XmlSlurper
and return it.
- Convert the response to a
String
and return it.
The default values for the configuration properties that affect the response conversion are:
Property | Default |
---|
binaryResponse | false |
rawClientResponse | false |
convertJson | true |
convertXML | true |
The OPTIONS
and HEAD
methods only return a ClientResponse
as the responses for these methods do not contain bodies.
4.2 HTTP Status Exceptions
The builder, by default, will do automation conversion of the message and return it if the HTTP status returned with the request is considered
successful. For the purposes of the builder,
successful is defined as an HTTP status code in the 2xx range of codes (for example, 200 and 201).
If a non-successful HTTP status code is encountered, an exception is thrown. Most well-known HTTP status codes are represented by an appropriately named exception, and they all
extend a common base exception
ResponseStatusException
. If a code is received that the builder does not have a named exception for, a
ResponseStatusException
is thrown.
The behavior to throw an exception for a non-successful HTTP status can be disabled by setting the RequestBuilder
property skipStatusCheck
to true
.
The
ResponseStatusException
contains the following:
Property | Description | Type |
---|
content | The converted response message. | mixed |
logText | Debug log (if enabled) | String |
response | The ClientResponse returned from the Jersey-Client library. | ClientResponse |
status | HTTP status code. | Integer |
The following named HTTP status exceptions defined by the plugin are:
HTTP Status Code | Exception |
---|
300 | HttpMultipleChoicesException |
301 | HttpMovedPermanentlyException |
302 | HttpFoundException |
303 | HttpSeeOtherException |
304 | HttpNotModifiedException |
305 | HttpUseProxyException |
307 | HttpTemporaryRedirectException |
400 | HttpBadRequestException |
401 | HttpUnauthorizedException |
402 | HttpPaymentRequiredException |
403 | HttpForbiddenException |
404 | HttpNotFoundException |
405 | HttpMethodNotAllowedException |
406 | HttpNotAcceptableException |
407 | HttpProxyAuthenticationRequiredException |
408 | HttpRequestTimeoutException |
409 | HttpConflictException |
410 | HttpGoneException |
411 | HttpLengthRequiredException |
412 | HttpPreconditionFailedException |
413 | HttpRequestEntityTooLargeException |
414 | HttpRequestUriTooLongException |
415 | HttpUnsupportedMediaTypeException |
416 | HttpRequestedRangeNotSatisfiableException |
417 | HttpExpectationFailedException |
422 | HttpUnprocessableEntityException |
500 | HttpInternalServerErrorException |
501 | HttpNotImplementedException |
502 | HttpBadGatewayException |
503 | HttpServiceUnavailableException |
504 | HttpGatewayTimeoutException |
505 | HttpHttpVersionNotSupportedException |