groovyx.net.http
Class HTTPBuilder.RequestConfigDelegate

java.lang.Object
  groovyx.net.http.HTTPBuilder.RequestConfigDelegate

Enclosing class:

HTTPBuilder

protected class HTTPBuilder.RequestConfigDelegate
extends Object

Encloses all properties and method calls used within the HTTPBuilder.request(Object, Method, Object, Closure) 'config' closure argument. That is, an instance of this class is set as the closure's delegate. This allows the user to configure various parameters within the scope of a single request.

All properties of this class are available from within the closure. For example, you can manipulate various aspects of the default request URI for this request by calling uri.path = '/api/location'. This allows for the ability to modify parameters per-request while leaving any values set directly on the HTTPBuilder instance unchanged for subsequent requests.

Constructor Summary

HTTPBuilder.RequestConfigDelegate(org.apache.http.client.methods.HttpRequestBase request, Object contentType, Map<?,?> defaultRequestHeaders, Map<?,groovy.lang.Closure> defaultResponseHandlers)

HTTPBuilder.RequestConfigDelegate(Map<String,?> args, org.apache.http.client.methods.HttpRequestBase request, groovy.lang.Closure successHandler)

Method Summary

protected groovy.lang.Closure	findResponseHandler(int statusCode) Get the proper response handler for the response code.
protected Object	getContentType() Get the content-type of any data sent in the request body and the expected response content-type.
HttpContextDecorator	getContext() Get the HttpContext that will be used for this request.
Map<?,?>	getHeaders() Get request headers (including any default headers set on this HTTPBuilder instance).
protected org.apache.http.client.methods.HttpRequestBase	getRequest() Directly access the Apache HttpClient instance that will be used to execute this request.
protected Object	getRequestContentType() The request content-type, if different from the contentType.
Map<Object,groovy.lang.Closure>	getResponse() Access the response handler map to set response parsing logic.
URIBuilder	getUri() Use this object to manipulate parts of the request URI, like query params and request path.
void	send(Object contentType, Object requestBody) Convenience method to set a request content-type at the same time the request body is set.
void	setBody(Object body) Set the request body.
protected void	setContentType(Object ct) Set the content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
void	setContext(org.apache.http.protocol.HttpContext ctx) Set the HttpContext that will be used for this request.
void	setHeaders(Map<?,?> newHeaders) Set request headers.
protected void	setPropertiesFromMap(Map<String,?> args) Valid arguments: uriEither a URI, URL, or object whose toString() method produces a valid URI string.
protected void	setRequestContentType(Object ct) Assign a different content-type for the request than is expected for the response.
void	setUri(Object uri) Set the entire URI to be used for this request.

Methods inherited from class java.lang.Object

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

Constructor Detail

HTTPBuilder.RequestConfigDelegate

public HTTPBuilder.RequestConfigDelegate(org.apache.http.client.methods.HttpRequestBase request,
                                         Object contentType,
                                         Map<?,?> defaultRequestHeaders,
                                         Map<?,groovy.lang.Closure> defaultResponseHandlers)

HTTPBuilder.RequestConfigDelegate

public HTTPBuilder.RequestConfigDelegate(Map<String,?> args,
                                         org.apache.http.client.methods.HttpRequestBase request,
                                         groovy.lang.Closure successHandler)
                                  throws URISyntaxException

Throws:

URISyntaxException

Method Detail

getUri

public URIBuilder getUri()

Use this object to manipulate parts of the request URI, like query params and request path. Example:

 builder.request(GET,XML) {
   uri.path = '../other/request.jsp'
   uri.query = [p1:1, p2:2]
   ...
 }

This method signature returns Object so that the complementary setUri(Object) method can accept various types.

Returns:

URIBuilder to manipulate the request URI

setUri

public void setUri(Object uri)
            throws URISyntaxException

Set the entire URI to be used for this request. Acceptable parameter types are:

• URL
• URI
• URIBuilder

Any other parameter type will be assumed that its toString() method produces a valid URI.

Note that if you want to change just a portion of the request URI, (e.g. the host, port, path, etc.) you can call getUri() which will return a URIBuilder which can manipulate portions of the request URI.

Parameters:

uri - the URI to use for this request.

Throws:

URISyntaxException - if an argument is given that is not a valid URI

See Also:

URIBuilder.convertToURI(Object)

getRequest

protected org.apache.http.client.methods.HttpRequestBase getRequest()

Directly access the Apache HttpClient instance that will be used to execute this request.

See Also:

HttpRequestBase

getContentType

protected Object getContentType()

Get the content-type of any data sent in the request body and the expected response content-type. If the request content-type is expected to differ from the response content-type (i.e. a URL-encoded POST that should return an HTML page) then this value will be used for the response content-type, while #setRequestContentType(String) should be used for the request.

Returns:

whatever value was assigned via setContentType(Object) or passed from the HTTPBuilder.defaultContentType when this RequestConfigDelegate instance was constructed.

setContentType

protected void setContentType(Object ct)

Set the content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response. The value should be either a ContentType value or a String, i.e. "text/plain". This will default to HTTPBuilder.getContentType() for requests that do not explicitly pass a contentType parameter (such as HTTPBuilder.request(Method, Object, Closure)).

Parameters:

ct - the value that will be used for the Content-Type and Accept request headers.

getRequestContentType

protected Object getRequestContentType()

The request content-type, if different from the contentType.

Returns:

either a ContentType value or String like text/plain

setRequestContentType

protected void setRequestContentType(Object ct)

Assign a different content-type for the request than is expected for the response. This is useful if i.e. you want to post URL-encoded form data but expect the response to be XML or HTML. The getContentType() will always control the Accept header, and will be used for the request content unless this value is also explicitly set.

Note that this method is used internally; calls within a request configuration closure should call send(Object, Object) to set the request body and content-type at the same time.

Parameters:

ct - either a ContentType value or a valid content-type String.

setPropertiesFromMap

protected void setPropertiesFromMap(Map<String,?> args)
                             throws URISyntaxException

Valid arguments:

uri

Either a URI, URL, or object whose toString() method produces a valid URI string. If this parameter is not supplied, the HTTPBuilder's default URI is used.

path

Request path that is merged with the URI

queryString

an escaped query string

query

Map of URL query parameters

headers

Map of HTTP headers

contentType

Request content type and Accept header. If not supplied, the HTTPBuilder's default content-type is used.

requestContentType

content type for the request, if it is different from the expected response content-type

body

Request body that will be encoded based on the given contentType

Note that if both queryString and query are given, query will be merged with (and potentially override) the parameters given as part of queryString.

Parameters:

args - named parameters to set properties on this delegate.

Throws:

URISyntaxException - if the uri argument does not represent a valid URI

setHeaders

public void setHeaders(Map<?,?> newHeaders)

Set request headers. These values will be merged with any default request headers. (The assumption is you'll probably want to add a bunch of headers to whatever defaults you've already set). If you only want to use values set here, simply call headers.clear() first.

getHeaders

public Map<?,?> getHeaders()

Get request headers (including any default headers set on this HTTPBuilder instance). Note that this will not include any Accept, Content-Type, or Content-Encoding headers that are automatically handled by any encoder or parsers in effect. Note that any values set here will override any of those automatically assigned values.

Example: headers.'Accept-Language' = 'en, en-gb;q=0.8'

Returns:

a map of HTTP headers that will be sent in the request.

send

public void send(Object contentType,
                 Object requestBody)

Convenience method to set a request content-type at the same time the request body is set. This is a variation of setBody(Object) that allows for a different content-type than what is expected for the response.

Example:

 http.request(POST,HTML) {

   /* request data is interpreted as a JsonBuilder closure by
      HTTPBuilder's default EncoderRegistry implementation * /
   send( 'text/javascript' ) {
     a : ['one','two','three']
   }

   // response content-type is what was specified in the outer request() argument:
   response.success = { resp, html ->

   }
 }
 

The send call is equivalent to the following:

   requestContentType = 'text/javascript'
   body = { a : ['one','two','three'] }
 

Parameters:

contentType - either a ContentType or equivalent content-type string like "text/xml"

requestBody -

setBody

public void setBody(Object body)

Set the request body. This value may be of any type supported by the associated request encoder. That is, the value of body will be interpreted by the encoder associated with the current request content-type.

Parameters:

body - data or closure interpreted as the request body

See Also:

send(Object, Object)

findResponseHandler

protected groovy.lang.Closure findResponseHandler(int statusCode)

Get the proper response handler for the response code. This is called by the HTTPBuilder class in order to find the proper handler based on the response status code.

Parameters:

statusCode - HTTP response status code

Returns:

the response handler

getResponse

public Map<Object,groovy.lang.Closure> getResponse()

Access the response handler map to set response parsing logic. i.e.

 builder.request( GET, XML ) {
   response.success = { xml ->
      /* for XML content type, the default parser
         will return an XmlSlurper * /
      xml.root.children().each { println it }
   }
 }

Returns:

getContext

public HttpContextDecorator getContext()

Get the HttpContext that will be used for this request. By default, a new context is created for each request.

Returns:

See Also:

ClientContext

setContext

public void setContext(org.apache.http.protocol.HttpContext ctx)

Set the HttpContext that will be used for this request.

Parameters:

ctx -