groovyx.net.http
Class HttpURLClient

java.lang.Object
  groovyx.net.http.HttpURLClient

public class HttpURLClient
extends Object

This class provides a simplified API similar to HTTPBuilder, but uses HttpURLConnection for I/O so that it is compatible with Google App Engine. Features:

• Parser and Encoder support
• Easy request and response header manipulation
• Basic authentication

Notably absent are status-code based response handling and the more complex authentication mechanisms.

TODO request encoding support (if anyone asks for it)

Since:

0.5.0

Author:

Tom Nichols

See Also:

GAE URLFetch

Field Summary

protected org.apache.commons.logging.Log	log Logger instance defined for use by sub-classes
protected groovyx.net.http.HttpURLClient.OAuthWrapper	oauth

Constructor Summary

HttpURLClient()

Method Summary

Object	getContentType() Get the default content-type used for parsing response data.
EncoderRegistry	getEncoders() Get the encoder registry used by this instance, which can be used to directly modify the request serialization behavior.
Map<String,String>	getHeaders() Retrieve the default headers that will be sent in each request.
ParserRegistry	getParsers() Retrieve the parser registry used by this instance, which can be used to directly modify the parsing behavior.
Object	getRequestContentType() Get the default content-type used to serialize the request data.
Object	getUrl() The default URL for this request.
boolean	isFollowRedirects() See setFollowRedirects(boolean)
HttpResponseDecorator	request(Map<String,?> args) Perform a request.
void	setBasicAuth(Object user, Object pass) Set basic user and password authorization to be used for every request.
void	setContentType(Object ct) Set the default content-type used to control response parsing and request serialization behavior.
void	setEncoders(EncoderRegistry encoderRegistry)
void	setFollowRedirects(boolean follow) Control whether this instance should automatically follow redirect responses.
void	setHeaders(Map<?,?> headers) Set default headers to be sent with every request.
void	setOAuth(Object consumerKey, Object consumerSecret, Object accessToken, Object accessSecret) Sign all outbound requests with the given OAuth keys and tokens.
void	setParsers(ParserRegistry parserRegistry)
void	setRequestContentType(Object requestContentType) Set the default content-type used to control request body serialization.
void	setUrl(Object url) Set the default request URL.

Methods inherited from class java.lang.Object

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

Field Detail

oauth

protected groovyx.net.http.HttpURLClient.OAuthWrapper oauth

log

protected org.apache.commons.logging.Log log

Logger instance defined for use by sub-classes

Constructor Detail

HttpURLClient

public HttpURLClient()

Method Detail

request

public HttpResponseDecorator request(Map<String,?> args)
                              throws URISyntaxException,
                                     MalformedURLException,
                                     IOException

Perform a request. Parameters are:

url

the entire request URL

path

the path portion of the request URL, if a default URL is set on this instance.

query

URL query parameters for this request.

timeout

see URLConnection.setReadTimeout(int)

method

This defaults to GET, or POST if a body parameter is also specified.

contentType

Explicitly specify how to parse the response. If this value is ContentType.ANY, the response Content-Type header is used to determine how to parse the response.

requestContentType

used in a PUT or POST request to transform the request body and set the proper Content-Type header. This defaults to the contentType if unset.

auth

Basic authorization; pass the value as a list in the form [user, pass]

headers

additional request headers, as a map

body

request content body, for a PUT or POST request. This will be encoded using the requestContentType

Parameters:

args - named parameters

Returns:

the parsed response

Throws:

URISyntaxException

MalformedURLException

IOException

setBasicAuth

public void setBasicAuth(Object user,
                         Object pass)
                  throws UnsupportedEncodingException

Set basic user and password authorization to be used for every request. Pass null to un-set authorization for this instance.

Parameters:

user -

pass -

Throws:

UnsupportedEncodingException

setOAuth

public void setOAuth(Object consumerKey,
                     Object consumerSecret,
                     Object accessToken,
                     Object accessSecret)

Sign all outbound requests with the given OAuth keys and tokens. It is assumed you have already generated a consumer keypair and retrieved a proper access token pair from your target service (see Signpost documentation for more details.) Once this has been done all requests will be signed.

Parameters:

consumerKey - null if you want to _stop_ signing requests.

consumerSecret -

accessToken -

accessSecret -

setFollowRedirects

public void setFollowRedirects(boolean follow)

Control whether this instance should automatically follow redirect responses. See HttpURLConnection.setInstanceFollowRedirects(boolean)

Parameters:

follow - true if the connection should automatically follow redirect responses from the server.

isFollowRedirects

public boolean isFollowRedirects()

See setFollowRedirects(boolean)

Returns:

getUrl

public Object getUrl()

The default URL for this request. This is a URIBuilder which can be used to easily manipulate portions of the request URL.

Returns:

setUrl

public void setUrl(Object url)
            throws URISyntaxException

Set the default request URL.

Parameters:

url - any object whose toString() produces a valid URI.

Throws:

URISyntaxException

See Also:

URIBuilder.convertToURI(Object)

getHeaders

public Map<String,String> getHeaders()

Retrieve the default headers that will be sent in each request. Note that this is a 'live' map that can be directly manipulated to add or remove the default request headers.

Returns:

setHeaders

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

Set default headers to be sent with every request.

Parameters:

headers -

getEncoders

public EncoderRegistry getEncoders()

Get the encoder registry used by this instance, which can be used to directly modify the request serialization behavior. i.e. client.encoders.'application/xml' = {....}.

Returns:

setEncoders

public void setEncoders(EncoderRegistry encoderRegistry)

getParsers

public ParserRegistry getParsers()

Retrieve the parser registry used by this instance, which can be used to directly modify the parsing behavior.

Returns:

setParsers

public void setParsers(ParserRegistry parserRegistry)

getContentType

public Object getContentType()

Get the default content-type used for parsing response data.

Returns:

a String or ContentType object. Defaults to ContentType.ANY

setContentType

public void setContentType(Object ct)

Set the default content-type used to control response parsing and request serialization behavior. If null is passed, ContentType.ANY will be used. If this value is ContentType.ANY, the response Content-Type header is used to parse the response.

Parameters:

ct - a String or ContentType value.

getRequestContentType

public Object getRequestContentType()

Get the default content-type used to serialize the request data.

Returns:

setRequestContentType

public void setRequestContentType(Object requestContentType)

Set the default content-type used to control request body serialization. If null, the contentType property is used. Additionally, if the contentType is ContentType.ANY, a requestContentType must be specified when performing a POST or PUT request that sends request data.

Parameters:

requestContentType - String or ContentType value.