Class RESTClient
- Access to response headers. All "request" methods on this class by
default return an instance of
HttpResponseDecorator
, which allows for simple evaluation of the response. - No streaming responses. Responses are expected to either not carry data
(in the case of HEAD or DELETE) or be parse-able into some sort of object.
That object is accessible via
HttpResponseDecorator.getData()
.
By default, all request method methods will return a HttpResponseDecorator
instance, which provides convenient access to response headers and the parsed
response body. The response body is parsed based on content-type, identical
to how HTTPBuilder's default response handler
functions.
Failed requests (i.e. responses which return a status code > 399) will
by default throw a HttpResponseException
. This exception may be used
to retrieve additional information regarding the response as well.
- Since:
- 0.5
-
Nested Class Summary
Nested classes/interfaces inherited from class groovyx.net.http.HTTPBuilder
HTTPBuilder.RequestConfigDelegate
-
Field Summary
Fields inherited from class groovyx.net.http.HTTPBuilder
auth, autoAcceptHeader, contentEncodingHandler, defaultContentType, defaultRequestContentType, defaultRequestHeaders, defaultResponseHandlers, defaultURI, encoders, log, parsers
-
Constructor Summary
ConstructorsConstructorDescriptionConstructor.RESTClient
(Object defaultURI) RESTClient
(Object defaultURI, Object defaultContentType) -
Method Summary
Modifier and TypeMethodDescriptionprotected void
defaultFailureHandler
(HttpResponseDecorator resp, Object data) Throws an exception for non-successful HTTP response codes.protected HttpResponseDecorator
defaultSuccessHandler
(HttpResponseDecorator resp, Object data) Returns anHttpResponseDecorator
, which provides simplified access to headers, response code, and parsed response body, as well as the underlyingHttpResponse
instance.Perform a DELETE request.Convenience method to perform an HTTP GET request.Perform a HEAD request, often used to check preconditions before sending a large PUT or POST request.Perform an OPTIONS request.Convenience method to perform a PATCH request.Convenience method to perform a POST request.Convenience method to perform a PUT request.Methods inherited from class groovyx.net.http.HTTPBuilder
buildDefaultResponseHandlers, createClient, defaultFailureHandler, doRequest, doRequest, get, getAuth, getClient, getContentType, getEncoder, getHandler, getHeaders, getParser, getUri, ignoreSSLIssues, isAutoAcceptHeader, parseResponse, post, request, request, request, setAuthConfig, setAutoAcceptHeader, setClient, setContentEncoding, setContentEncodingRegistry, setContentType, setEncoderRegistry, setHeaders, setParserRegistry, setProxy, setUri, shutdown
-
Constructor Details
-
RESTClient
public RESTClient()Constructor.- See Also:
-
RESTClient
- Parameters:
defaultURI
- default request URI (String, URI, URL orURIBuilder
)- Throws:
URISyntaxException
-
RESTClient
- Parameters:
defaultURI
- default request URI (String, URI, URL orURIBuilder
)defaultContentType
- default content-type (String orContentType
)- Throws:
URISyntaxException
-
-
Method Details
-
get
public Object get(Map<String, ?> args) throws org.apache.http.client.ClientProtocolException, IOException, URISyntaxExceptionConvenience method to perform an HTTP GET request. It will use the HTTPBuilder's
registered response handlers
to handle success or failure status codes. By default, thedefaultSuccessHandler(HttpResponseDecorator, Object)
success
response handler will return a decorated response object that can be used to read response headers and data.A 'failed' response (i.e. any HTTP status code > 399) will be handled by the registered 'failure' handler. The
default failure handler
throws aHttpResponseException
.- Overrides:
get
in classHTTPBuilder
- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
URISyntaxException
IOException
org.apache.http.client.ClientProtocolException
- See Also:
-
post
public Object post(Map<String, ?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOExceptionConvenience method to perform a POST request.
The request body (specified by a
body
named parameter) will be encoded based on therequestContentType
named parameter, or if none is given, the defaultcontent-type
for this instance.- Overrides:
post
in classHTTPBuilder
- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
- See Also:
-
put
public Object put(Map<String, ?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOExceptionConvenience method to perform a PUT request.
The request body (specified by a
body
named parameter) will be encoded based on therequestContentType
named parameter, or if none is given, the defaultcontent-type
for this instance.- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
-
patch
public Object patch(Map<String, ?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOExceptionConvenience method to perform a PATCH request.
The request body (specified by a
body
named parameter) will be encoded based on therequestContentType
named parameter, or if none is given, the defaultcontent-type
for this instance.- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
-
head
public Object head(Map<String, ?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOExceptionPerform a HEAD request, often used to check preconditions before sending a large PUT or POST request.
- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
-
delete
public Object delete(Map<String, ?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOExceptionPerform a DELETE request. This method does not accept a
body
argument.- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
-
options
public Object options(Map<String, ?> args) throws org.apache.http.client.ClientProtocolException, IOException, URISyntaxExceptionPerform an OPTIONS request.
- Parameters:
args
- named parameters - seeHTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
- Returns:
- a
HttpResponseDecorator
, unless the default success handler is overridden. - Throws:
org.apache.http.client.ClientProtocolException
IOException
URISyntaxException
-
defaultSuccessHandler
protected HttpResponseDecorator defaultSuccessHandler(HttpResponseDecorator resp, Object data) throws ResponseParseException Returns anHttpResponseDecorator
, which provides simplified access to headers, response code, and parsed response body, as well as the underlyingHttpResponse
instance.- Overrides:
defaultSuccessHandler
in classHTTPBuilder
- Parameters:
resp
- HTTP responsedata
- parsed data as resolved from this instance'sParserRegistry
- Returns:
- the parsed data object (whatever the parser returns).
- Throws:
ResponseParseException
- if there is an error buffering a streaming response.
-
defaultFailureHandler
protected void defaultFailureHandler(HttpResponseDecorator resp, Object data) throws HttpResponseException Throws an exception for non-successful HTTP response codes. The exception instance will have a reference to the response object, in order to inspect status code and headers within thecatch
block.- Parameters:
resp
- response objectdata
- parsed response data- Throws:
HttpResponseException
- exception which can access the response object.
-