groovyx.net.http
Class RESTClient

java.lang.Object  extended by groovyx.net.http.HTTPBuilder      extended by 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  voiddefaultFailureHandler(HttpResponseDecorator resp, Object data)
          Throws an exception for non-successful HTTP response codes.
protected  HttpResponseDecoratordefaultSuccessHandler(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.
 Objectdelete(Map<String,?> args)
          Perform a DELETE request.
 Objectget(Map<String,?> args)
          Convenience method to perform an HTTP GET request.
 Objecthead(Map<String,?> args)
          Perform a HEAD request, often used to check preconditions before sending a large PUT or POST request.
 Objectoptions(Map<String,?> args)
          Perform an OPTIONS request.
 Objectpost(Map<String,?> args)
          Convenience method to perform a POST request.
 Objectput(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.


Copyright © 2008-2012. All Rights Reserved.


NOTHING
NOTHING
Add the Maven Dependecy to your project: maven dependecy for com.amazonaws : aws-java-sdk : 1.3.14