(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 |