groovyx.net.http
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'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

Author:

Tom Nichols

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, client, contentEncodingHandler, defaultContentType, defaultRequestContentType, defaultRequestHeaders, defaultResponseHandlers, defaultURI, encoders, log, parsers

Constructor Summary

RESTClient()
Constructor.

RESTClient(Object defaultURI)
See HTTPBuilder.HTTPBuilder(Object)

RESTClient(Object defaultURI, Object defaultContentType)
See HTTPBuilder.HTTPBuilder(Object, Object)

Method Summary

protected void	defaultFailureHandler(HttpResponseDecorator resp, Object data) Throws an exception for non-successful HTTP response codes.
protected HttpResponseDecorator	defaultSuccessHandler(HttpResponseDecorator resp, Object data) Returns an HttpResponseDecorator, which provides simplified access to headers, response code, and parsed response body, as well as the underlying HttpResponse 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	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, isAutoAcceptHeader, parseResponse, post, request, request, request, setAuthConfig, setAutoAcceptHeader, setContentEncoding, setContentEncodingRegistry, setContentType, setEncoderRegistry, setHeaders, setParserRegistry, setProxy, setUri, shutdown

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RESTClient

public RESTClient()

Constructor.

See Also:

HTTPBuilder.HTTPBuilder()

RESTClient

public RESTClient(Object defaultURI)
           throws URISyntaxException

See HTTPBuilder.HTTPBuilder(Object)

Parameters:

defaultURI - default request URI (String, URI, URL or URIBuilder)

Throws:

URISyntaxException

RESTClient

public RESTClient(Object defaultURI,
                  Object defaultContentType)
           throws URISyntaxException

See HTTPBuilder.HTTPBuilder(Object, Object)

Parameters:

defaultURI - default request URI (String, URI, URL or URIBuilder)

defaultContentType - default content-type (String or ContentType)

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, the defaultSuccessHandler(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 a HttpResponseException.

Overrides:

get in class HTTPBuilder

Parameters:

args - named parameters - see HTTPBuilder.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 the requestContentType named parameter, or if none is given, the default content-type for this instance.

Overrides:

post in class HTTPBuilder

Parameters:

args - named parameters - see HTTPBuilder.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 the requestContentType named parameter, or if none is given, the default content-type for this instance.

Parameters:

args - named parameters - see HTTPBuilder.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 - see HTTPBuilder.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 - see HTTPBuilder.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 - see HTTPBuilder.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 an HttpResponseDecorator, which provides simplified access to headers, response code, and parsed response body, as well as the underlying HttpResponse instance.

Overrides:

defaultSuccessHandler in class HTTPBuilder

Parameters:

resp - HTTP response

data - parsed data as resolved from this instance's ParserRegistry

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 the catch block.

Parameters:

resp - response object

data - parsed response data

Throws:

HttpResponseException - exception which can access the response object.