groovyx.net.http
Class HTTPBuilder

java.lang.Object
  extended by groovyx.net.http.HTTPBuilder
Direct Known Subclasses:
AsyncHTTPBuilder

public class HTTPBuilder
extends Object

Groovy DSL for easily making HTTP requests, and handling request and response data. This class adds a number of convenience mechanisms built on top of Apache HTTPClient for things like URL-encoded POSTs and REST requests that require building and parsing JSON or XML. Convenient access to a few common authentication methods is also available.

Conventions

HTTPBuilder has properties for default headers, URL, contentType, etc. All of these values are also assignable (and in many cases, in much finer detail) from the HTTPBuilder.SendDelegate as well. In any cases where the value is not set on the delegate (from within a request closure,) the builder's default value is used.

For instance, any methods that do not take a URL parameter assume you will set a URL value in the request closure or use the builder's assigned default URL.

Response Parsing

By default, HTTPBuilder uses ContentType.ANY as the default content-type. This means the value of the request's Accept header is */*, and the response parser is determined based on the response content-type header.

If any contentType is given (either in setContentType(Object) or as a request method parameter), the builder will attempt to parse the response using that content-type, regardless of what the server actually responds with.

Examples:

Perform an HTTP GET and print the response:
   def http = new HTTPBuilder('http://www.google.com')
   
   http.get( path : '/search', 
             contentType : TEXT,
             query : [q:'Groovy'] ) { resp, reader ->
     println "response status: ${resp.statusLine}"
     println 'Response data: -----'
     System.out << reader
     println '\n--------------------'
   }
 
Long form for other HTTP methods, and response-code-specific handlers. This is roughly equivalent to the above example.
   def http = new HTTPBuilder('http://www.google.com/search?q=groovy')
   
   http.request( GET, TEXT ) { req ->
   
     // executed for all successful responses:
     response.success = { resp, reader ->
       println 'my response handler!'
       assert resp.statusLine.statusCode == 200
       println resp.statusLine
       System.out << reader // print response stream
     }
     
     // executed only if the response status code is 401:
     response.'404' = { resp -> 
       println 'not found!'
     }
   }
 
You can also set a default response handler called for any status code > 399 that is not matched to a specific handler. Setting the value outside a request closure means it will apply to all future requests with this HTTPBuilder instance:
   http.handler.failure = { resp ->
     println "Unexpected failure: ${resp.statusLine}"
   }
 
And... Automatic response parsing for registered content types!
   http.request( 'http://ajax.googleapis.com', GET, JSON ) {
     url.path = '/ajax/services/search/web'
     url.query = [ v:'1.0', q: 'Calvin and Hobbes' ]
     
     response.success = { resp, json ->
       assert json.size() == 3
       println "Query response: "
       json.responseData.results.each {
         println "  ${it.titleNoFormatting} : ${it.visibleUrl}"
       }
     }
   }
 

Author:
Tom Nichols

Nested Class Summary
protected  class HTTPBuilder.SendDelegate
          Encloses all properties and method calls used within the request(Object, Method, Object, Closure) 'config' closure argument.
 
Field Summary
protected  AuthConfig auth
           
protected  AbstractHttpClient client
           
protected  ContentEncodingRegistry contentEncodingHandler
           
protected  Object defaultContentType
           
protected  Map<String,String> defaultRequestHeaders
           
protected  Map<String,Closure> defaultResponseHandlers
           
protected  URI defaultURI
           
protected  EncoderRegistry encoders
           
protected  org.apache.commons.logging.Log log
           
protected  ParserRegistry parsers
           
 
Constructor Summary
HTTPBuilder()
           
HTTPBuilder(Object defaultURL)
          Give a default URL to be used for all request methods that don't explicitly take a URL parameter.
HTTPBuilder(Object defaultURL, Object defaultContentType)
          Give a default URL to be used for all request methods that don't explicitly take a URL parameter, and a default content-type to be used for request encoding and response parsing.
 
Method Summary
protected  Map<String,Closure> buildDefaultResponseHandlers()
           
protected  void defaultFailureHandler(HttpResponse resp)
          This is the default response.failure handler.
protected  void defaultSuccessHandler(HttpResponse resp)
          This is the default response.success handler.
protected  Object doRequest(HTTPBuilder.SendDelegate delegate)
           
protected  Object doRequest(URI uri, Method method, Object contentType, Closure configClosure)
           
 Object get(Map<String,?> args, Closure responseClosure)
          Convenience method to perform an HTTP GET.
 AuthConfig getAuth()
          Used to access the AuthConfig handler used to configure common authentication mechanism.
 AbstractHttpClient getClient()
          Return the underlying HTTPClient that is used to handle HTTP requests.
 Map<String,Closure> getEncoder()
          Retrieve the map of registered request content-type encoders.
 Map<String,Closure> getHandler()
          Retrieve the map of response code handlers.
 Map<String,String> getHeaders()
          Get the map of default headers that will be added to all requests.
 Map<String,Closure> getParser()
          Retrieve the map of registered response content-type parsers.
 Object getURL()
          Get the default URL used for requests that do not explicitly take a url param.
 Object post(Map<String,?> args, Closure responseClosure)
           Convenience method to perform an HTTP form POST.
 Object request(Method m, Closure configClosure)
           
 Object request(Method m, Object contentType, Closure configClosure)
           
 Object request(Object uri, Method method, Object contentType, Closure configClosure)
          Make a request for the given HTTP method and content-type, with additional options configured in the configClosure.
 void setAuthConfig(AuthConfig ac)
          Set an alternative AuthConfig implementation to handle authorization.
 void setContentEncoding(Object... encodings)
          Set acceptable request and response content-encodings.
 void setContentEncodingRegistry(ContentEncodingRegistry cer)
          Set a custom registry used to handle different content-encoding types in responses.
 void setContentType(Object ct)
          Set the default content type that will be used to select the appropriate request encoder and response parser.
 void setEncoderRegistry(EncoderRegistry er)
          Set a custom registry used to handle different request content-types.
 void setHeaders(Map<?,?> headers)
          Set the default headers to add to all requests made by this builder instance.
 void setParserRegistry(ParserRegistry pr)
          Set a custom registry used to handle different response content-types
 void setURL(Object url)
          Set the default URL used for requests that do not explicitly take a url param.
 void shutdown()
          Release any system resources held by this instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

client

protected AbstractHttpClient client

defaultURI

protected URI defaultURI

auth

protected AuthConfig auth

log

protected final org.apache.commons.logging.Log log

defaultContentType

protected Object defaultContentType

defaultResponseHandlers

protected final Map<String,Closure> defaultResponseHandlers

contentEncodingHandler

protected ContentEncodingRegistry contentEncodingHandler

defaultRequestHeaders

protected final Map<String,String> defaultRequestHeaders

encoders

protected EncoderRegistry encoders

parsers

protected ParserRegistry parsers
Constructor Detail

HTTPBuilder

public HTTPBuilder()

HTTPBuilder

public HTTPBuilder(Object defaultURL)
            throws URISyntaxException
Give a default URL to be used for all request methods that don't explicitly take a URL parameter.

Parameters:
defaultURL - either a URL, URI or String
Throws:
URISyntaxException - if the URL was not parse-able

HTTPBuilder

public HTTPBuilder(Object defaultURL,
                   Object defaultContentType)
            throws URISyntaxException
Give a default URL to be used for all request methods that don't explicitly take a URL parameter, and a default content-type to be used for request encoding and response parsing.

Parameters:
defaultURL - either a URL, URI or String
defaultContentType - content-type string. See ContentType for common types.
Throws:
URISyntaxException - if the URL was not parse-able
Method Detail

get

public Object get(Map<String,?> args,
                  Closure responseClosure)
           throws ClientProtocolException,
                  IOException,
                  URISyntaxException
Convenience method to perform an HTTP GET. The response closure will be called only on a successful response; a 'failed' response (i.e. any HTTP status code > 399) will be handled by the registered 'failure' handler. The default failure handler throws an HttpResponseException

Parameters:
args - see HTTPBuilder.SendDelegate.setPropertiesFromMap(Map)
responseClosure - code to handle a successful HTTP response
Returns:
any value returned by the response closure.
Throws:
ClientProtocolException
IOException
URISyntaxException

post

public Object post(Map<String,?> args,
                   Closure responseClosure)
            throws URISyntaxException,
                   ClientProtocolException,
                   IOException

Convenience method to perform an HTTP form POST. The response closure will be called only on a successful response; a 'failed' response (i.e. any HTTP status code > 399) will be handled by the registered 'failure' handler. The default failure handler throws an HttpResponseException.

The request body (specified by a body named parameter) will be converted to a url-encoded form string unless a different requestContentType named parameter is passed to this method. (See EncoderRegistry.encodeForm(Map).)

Parameters:
args - see HTTPBuilder.SendDelegate.setPropertiesFromMap(Map)
responseClosure - code to handle a successful HTTP response
Returns:
any value returned by the response closure.
Throws:
ClientProtocolException
IOException
URISyntaxException

request

public Object request(Method m,
                      Closure configClosure)
               throws ClientProtocolException,
                      IOException
Throws:
ClientProtocolException
IOException

request

public Object request(Method m,
                      Object contentType,
                      Closure configClosure)
               throws ClientProtocolException,
                      IOException
Throws:
ClientProtocolException
IOException

request

public Object request(Object uri,
                      Method method,
                      Object contentType,
                      Closure configClosure)
               throws ClientProtocolException,
                      IOException,
                      URISyntaxException
Make a request for the given HTTP method and content-type, with additional options configured in the configClosure. See HTTPBuilder.SendDelegate for options.

Parameters:
uri - either a URI, URL, or String
method - HTTP method
contentType - either a ContentType or valid content-type string.
configClosure - closure from which to configure options like url.path, request parameters, headers, request body and response handlers.
Returns:
whatever value was returned by the executed response handler.
Throws:
IllegalAccessException
InstantiationException
ClientProtocolException
IOException
URISyntaxException - if a URI string or URL was invalid.

doRequest

protected Object doRequest(URI uri,
                           Method method,
                           Object contentType,
                           Closure configClosure)
                    throws ClientProtocolException,
                           IOException
Throws:
ClientProtocolException
IOException

doRequest

protected Object doRequest(HTTPBuilder.SendDelegate delegate)
                    throws ClientProtocolException,
                           IOException
Throws:
ClientProtocolException
IOException

buildDefaultResponseHandlers

protected Map<String,Closure> buildDefaultResponseHandlers()

defaultSuccessHandler

protected void defaultSuccessHandler(HttpResponse resp)
                              throws IllegalStateException,
                                     IOException
This is the default response.success handler. It will be executed if no status-code-specific handler is set (i.e. response.'200'= {..}). This simply prints the status line and the response stream to System.out. In most cases you will want to define a response.success = {...} handler from the request closure, which will replace this method.

Parameters:
resp -
Throws:
IllegalStateException
IOException

defaultFailureHandler

protected void defaultFailureHandler(HttpResponse resp)
                              throws HttpResponseException
This is the default response.failure handler. It will be executed if no status-code-specific handler is set (i.e. response.'404'= {..}). This default handler will throw a HttpResponseException when executed. In most cases you will want to define your own response.failure = {...} handler from the request closure, if you don't want an exception to be thrown for a 4xx and 5xx status response.

Parameters:
resp -
Throws:
HttpResponseException

getHandler

public Map<String,Closure> getHandler()
Retrieve the map of response code handlers. Each map key is a response code as a string (i.e. '401') or either 'success' or 'failure'. Use this to set default response handlers, e.g.
builder.handler.'401' = { resp -> println "${resp.statusLine}" }

Returns:
See Also:
Status

getParser

public Map<String,Closure> getParser()
Retrieve the map of registered response content-type parsers. Use this to set default response parsers, e.g.
 builder.parser.'text/javascript' = { resp -> 
          return resp.entity.content // just returns an InputStream
 }

Returns:

getEncoder

public Map<String,Closure> getEncoder()
Retrieve the map of registered request content-type encoders. Use this to set a default request encoder, e.g.
 builder.encoder.'text/javascript' = { body ->
   def json = body.call( new JsonGroovyBuilder() )
   return new StringEntity( json.toString() )
 }

Returns:

setContentType

public void setContentType(Object ct)
Set the default content type that will be used to select the appropriate request encoder and response parser. The ContentType enum holds some common content-types that may be used, i.e.
 import static ContentType.*
 builder.contentType = XML
 

Parameters:
ct - either a ContentType or string value (i.e. "text/xml".)
See Also:
EncoderRegistry, ParserRegistry

setContentEncoding

public void setContentEncoding(Object... encodings)
Set acceptable request and response content-encodings.

Parameters:
encodings - each Object should be either a ContentEncoding.Type value, or a content-encoding string that is known by the ContentEncodingRegistry
See Also:
ContentEncodingRegistry

setURL

public void setURL(Object url)
            throws URISyntaxException
Set the default URL used for requests that do not explicitly take a url param.

Parameters:
url - a URL, URI, or String
Throws:
URISyntaxException

getURL

public Object getURL()
Get the default URL used for requests that do not explicitly take a url param.

Returns:
url a URL instance. Note that the return type is Object simply so that it matches with its JavaBean setURL(Object) counterpart.

setHeaders

public void setHeaders(Map<?,?> headers)
Set the default headers to add to all requests made by this builder instance. These values will replace any previously set default headers.

Parameters:
headers - map of header names & values.

getHeaders

public Map<String,String> getHeaders()
Get the map of default headers that will be added to all requests. This is a 'live' collection so it may be used to add or remove default values.

Returns:
the map of default header names and values.

getClient

public AbstractHttpClient getClient()
Return the underlying HTTPClient that is used to handle HTTP requests.

Returns:
the client instance.

getAuth

public AuthConfig getAuth()
Used to access the AuthConfig handler used to configure common authentication mechanism. Example:
builder.auth.basic( 'myUser', 'somePassword' )

Returns:

setAuthConfig

public void setAuthConfig(AuthConfig ac)
Set an alternative AuthConfig implementation to handle authorization.

Parameters:
ac - instance to use.

setEncoderRegistry

public void setEncoderRegistry(EncoderRegistry er)
Set a custom registry used to handle different request content-types.

Parameters:
er -

setParserRegistry

public void setParserRegistry(ParserRegistry pr)
Set a custom registry used to handle different response content-types

Parameters:
pr -

setContentEncodingRegistry

public void setContentEncodingRegistry(ContentEncodingRegistry cer)
Set a custom registry used to handle different content-encoding types in responses.

Parameters:
cer -

shutdown

public void shutdown()
Release any system resources held by this instance.

See Also:
ClientConnectionManager.shutdown()


Copyright © 2008. All Rights Reserved.