Class RESTClient
- java.lang.Object
-
- groovyx.net.http.HTTPBuilder
-
- groovyx.net.http.RESTClient
-
public class RESTClient extends HTTPBuilder
Extension to HTTPBuilder that basically attempts to provide a slightly more REST-ful face on top of HTTPBuilder. The differences between this class and HTTPBuilder are such:- 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'sdefault 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
- Author:
- Tom Nichols
- Access to response headers. All "request" methods on this class by
default return an instance of
-
-
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
Constructors Constructor Description RESTClient()
Constructor.RESTClient(Object defaultURI)
RESTClient(Object defaultURI, Object defaultContentType)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected 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.Object
delete(Map<String,?> args)
Perform a DELETE request.Object
get(Map<String,?> args)
Convenience method to perform an HTTP GET request.Object
head(Map<String,?> args)
Perform a HEAD request, often used to check preconditions before sending a large PUT or POST request.Object
options(Map<String,?> args)
Perform an OPTIONS request.Object
patch(Map<String,?> args)
Convenience method to perform a PATCH request.Object
post(Map<String,?> args)
Convenience method to perform a POST request.Object
put(Map<String,?> args)
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 Detail
-
RESTClient
public RESTClient()
Constructor.- See Also:
HTTPBuilder()
-
RESTClient
public RESTClient(Object defaultURI) throws URISyntaxException
- Parameters:
defaultURI
- default request URI (String, URI, URL orURIBuilder
)- Throws:
URISyntaxException
-
RESTClient
public RESTClient(Object defaultURI, Object defaultContentType) throws URISyntaxException
- Parameters:
defaultURI
- default request URI (String, URI, URL orURIBuilder
)defaultContentType
- default content-type (String orContentType
)- Throws:
URISyntaxException
-
-
Method Detail
-
get
public Object get(Map<String,?> args) throws org.apache.http.client.ClientProtocolException, IOException, URISyntaxException
Convenience 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:
defaultSuccessHandler(HttpResponseDecorator, Object)
,defaultFailureHandler(HttpResponseDecorator, Object)
-
post
public Object post(Map<String,?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOException
Convenience 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:
HTTPBuilder.getHandler()
,HTTPBuilder.defaultSuccessHandler(HttpResponseDecorator, Object)
,HTTPBuilder.defaultFailureHandler(HttpResponseDecorator)
-
put
public Object put(Map<String,?> args) throws URISyntaxException, org.apache.http.client.ClientProtocolException, IOException
Convenience 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, IOException
Convenience 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, IOException
Perform 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, IOException
Perform 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, URISyntaxException
Perform 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.
-
-