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

  1. If rawClientResponse is true, return the Jersey-Client ClientResponse object.
  2. If binaryResponse is true, return the response as a byte array.
  3. 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.
  4. If a Content-Type header that is XML compatible is received and convertXML is true, convert the response using XmlSlurper and return it.
  5. Convert the response to a String and return it.

The default values for the configuration properties that affect the response conversion are:

PropertyDefault
binaryResponsefalse
rawClientResponsefalse
convertJsontrue
convertXMLtrue

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:

PropertyDescriptionType
contentThe converted response message. mixed
logTextDebug log (if enabled)String
responseThe ClientResponse returned from the Jersey-Client library.ClientResponse
statusHTTP status code.Integer

The following named HTTP status exceptions defined by the plugin are:

HTTP Status CodeException
300HttpMultipleChoicesException
301HttpMovedPermanentlyException
302HttpFoundException
303HttpSeeOtherException
304HttpNotModifiedException
305HttpUseProxyException
307HttpTemporaryRedirectException
400HttpBadRequestException
401HttpUnauthorizedException
402HttpPaymentRequiredException
403HttpForbiddenException
404HttpNotFoundException
405HttpMethodNotAllowedException
406HttpNotAcceptableException
407HttpProxyAuthenticationRequiredException
408HttpRequestTimeoutException
409HttpConflictException
410HttpGoneException
411HttpLengthRequiredException
412HttpPreconditionFailedException
413HttpRequestEntityTooLargeException
414HttpRequestUriTooLongException
415HttpUnsupportedMediaTypeException
416HttpRequestedRangeNotSatisfiableException
417HttpExpectationFailedException
422HttpUnprocessableEntityException
500HttpInternalServerErrorException
501HttpNotImplementedException
502HttpBadGatewayException
503HttpServiceUnavailableException
504HttpGatewayTimeoutException
505HttpHttpVersionNotSupportedException