groovyx.net.http
Class AsyncHTTPBuilder

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

public class AsyncHTTPBuilder
extends HTTPBuilder

This implementation makes all requests asynchronous by submitting jobs to a ThreadPoolExecutor. All request methods (including get and post) return a Future instance, whose get method will provide access to whatever value was returned from the response handler closure.

Author:

Tom Nichols

Nested Class Summary

Nested classes/interfaces inherited from class groovyx.net.http.HTTPBuilder

HTTPBuilder.RequestConfigDelegate

Field Summary

static int	DEFAULT_POOL_SIZE Default pool size is one is not supplied in the constructor.
protected ExecutorService	threadPool

Fields inherited from class groovyx.net.http.HTTPBuilder

auth, autoAcceptHeader, client, contentEncodingHandler, defaultContentType, defaultRequestContentType, defaultRequestHeaders, defaultResponseHandlers, defaultURI, encoders, log, parsers

Constructor Summary

AsyncHTTPBuilder(Map<String,?> args)
Accepts the following named parameters: threadPoolCustom ExecutorService instance for running submitted requests.

Method Summary

protected void	defaultFailureHandler(HttpResponseDecorator resp) For 'failure' responses (e.g.
protected Object	defaultSuccessHandler(HttpResponseDecorator resp, Object parsedData) This is the default response.success handler.
protected Future<?>	doRequest(HTTPBuilder.RequestConfigDelegate delegate) Submits a Callable instance to the job pool, which in turn will call HTTPBuilder.doRequest(RequestConfigDelegate) in an asynchronous thread.
protected void	finalize()
ExecutorService	getThreadExecutor() Access the underlying threadpool to adjust things like job timeouts.
int	getTimeout() Get the timeout in for establishing an HTTP connection.
protected void	initThreadPools(int poolSize, ExecutorService threadPool) Initializes threading parameters for the HTTPClient's ThreadSafeClientConnManager, and this class' ThreadPoolExecutor.
void	setTimeout(int timeout) This timeout is used for both the time to wait for an established connection, and the time to wait for data.
void	shutdown() Release any system resources held by this instance.

Methods inherited from class groovyx.net.http.HTTPBuilder

buildDefaultResponseHandlers, createClient, doRequest, get, get, getAuth, getClient, getContentType, getEncoder, getHandler, getHeaders, getParser, getUri, isAutoAcceptHeader, parseResponse, post, post, request, request, request, setAuthConfig, setAutoAcceptHeader, setContentEncoding, setContentEncodingRegistry, setContentType, setEncoderRegistry, setHeaders, setParserRegistry, setProxy, setUri

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_POOL_SIZE

public static final int DEFAULT_POOL_SIZE

Default pool size is one is not supplied in the constructor.

See Also:

Constant Field Values

threadPool

protected ExecutorService threadPool

Constructor Detail

AsyncHTTPBuilder

public AsyncHTTPBuilder(Map<String,?> args)
                 throws URISyntaxException

Accepts the following named parameters:

threadPool

Custom ExecutorService instance for running submitted requests. If this is an instance of ThreadPoolExecutor, the poolSize will be determined by ThreadPoolExecutor.getMaximumPoolSize(). The default threadPool uses an unbounded queue to accept an unlimited number of requests.

poolSize

Max number of concurrent requests

uri

Default request URI

contentType

Default content type for requests and responses

timeout

Timeout in milliseconds to wait for a connection to be established and request to complete.

Throws:

URISyntaxException

Method Detail

doRequest

protected Future<?> doRequest(HTTPBuilder.RequestConfigDelegate delegate)

Submits a Callable instance to the job pool, which in turn will call HTTPBuilder.doRequest(RequestConfigDelegate) in an asynchronous thread. The Future instance returned by this value (which in turn should be returned by any of the public request methods (including get and post) may be used to retrieve whatever value may be returned from the executed response handler closure.

Overrides:

doRequest in class HTTPBuilder

initThreadPools

protected void initThreadPools(int poolSize,
                               ExecutorService threadPool)

Initializes threading parameters for the HTTPClient's ThreadSafeClientConnManager, and this class' ThreadPoolExecutor.

defaultSuccessHandler

protected Object defaultSuccessHandler(HttpResponseDecorator resp,
                                       Object parsedData)
                                throws ResponseParseException

This is the default response.success handler. It will be executed if the response is not handled by a status-code-specific handler (i.e. response.'200'= {..}) and no generic 'success' handler is given (i.e. response.success = {..}.) This handler simply returns the parsed data from the response body. In most cases you will probably want to define a response.success = {...} handler from the request closure, which will replace the response handler defined by this method.

Note for parsers that return streaming content:

For responses parsed as BINARY or TEXT, the parser will return streaming content -- an InputStream or Reader. In these cases, this handler will buffer the the response content before the network connection is closed.

In practice, a user-supplied response handler closure is designed to handle streaming content so it can be read directly from the response stream without buffering, which will be much more efficient. Therefore, it is recommended that request method variants be used which explicitly accept a response handler closure in these cases.

Overrides:

defaultSuccessHandler in class HTTPBuilder

Parameters:

resp - HTTP response

parsedData - 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)
                              throws HttpResponseException

For 'failure' responses (e.g. a 404), the exception will be wrapped in a ExecutionException and held by the Future instance. The exception is then re-thrown when calling future.get(). You can access the original exception (e.g. an HttpResponseException) by calling ex.getCause().

Overrides:

defaultFailureHandler in class HTTPBuilder

Throws:

HttpResponseException

setTimeout

public void setTimeout(int timeout)

This timeout is used for both the time to wait for an established connection, and the time to wait for data.

Parameters:

timeout - time to wait in milliseconds.

See Also:

HttpConnectionParams.setSoTimeout(HttpParams, int), HttpConnectionParams.setConnectionTimeout(HttpParams, int)

getTimeout

public int getTimeout()

Get the timeout in for establishing an HTTP connection.

Returns:

timeout in milliseconds.

getThreadExecutor

public ExecutorService getThreadExecutor()

Access the underlying threadpool to adjust things like job timeouts.

Note that this is not the same pool used by the HttpClient's ThreadSafeClientConnManager. Therefore, increasing the maximum pool size will not in turn increase the number of possible concurrent requests. It will simply cause more requests to be attempted which will then simply block while waiting for a free connection.

Returns:

the service used to execute requests. By default this is a ThreadPoolExecutor.

shutdown

public void shutdown()

Release any system resources held by this instance.

Overrides:

shutdown in class HTTPBuilder

See Also:

ClientConnectionManager.shutdown()

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

See Also:

shutdown()