diff --git a/src/docbkx/advanced.xml b/src/docbkx/advanced.xml index 85378d967..a1bdf4e3a 100644 --- a/src/docbkx/advanced.xml +++ b/src/docbkx/advanced.xml @@ -158,6 +158,117 @@ try { } finally { response2.close(); } +]]> + + +
+ Using the FutureRequestExecutionService + + Using the FutureRequestExecutionService, you can schedule http calls and treat the response + as a Future. This is useful when e.g. making multiple calls to a web service. The advantage of using + the FutureRequestExecutionService is that you can use multiple threads to schedule requests concurrently, set timeouts on + the tasks, or cancel them when a response is no longer necessary. + + + FutureRequestExecutionService wraps the request with a HttpRequestFutureTask, which extends FutureTask. This + class allows you to cancel the task as well as keep track of various metrics such as request duration. + +
+ Creating the FutureRequestExecutionService + The constructor for the futureRequestExecutionService takes any existing httpClient instance and an ExecutorService + instance. When configuring both, it is important to align the maximum number of connections with the number of threads + you are going to use. When there are more threads than connections, the connections may start timing out because there are no + available connections. When there are more connections than threads, the futureRequestExecutionService will not use all of them + + +
+ +
+ Scheduling requests + To schedule a request, simply provide a HttpUriRequest, HttpContext, and a ResponseHandler. Because + the request is processed by the executor service, a ResponseHandler is mandatory. + + { + public Boolean handleResponse( + final HttpResponse response) throws ClientProtocolException, IOException { + return response.getStatusLine().getStatusCode() == 200; + } +} + +HttpRequestFutureTask task = futureRequestExecutionService.execute( + new HttpGet("http://www.google.com"), HttpClientContext.create(), + new OkidokiHandler()); +// blocks until the request complete and then returns true if you can connect to Google +boolean ok=task.get(); +]]> +
+
+ Canceling tasks + Scheduled tasks may be cancelled. If the task is not yet executing but merely queued for execution, it simply will never execute. If it is executing and the mayInterruptIfRunning parameter is set to true, abort() will be called on the request; otherwise the response will simply be ignored but the request will be allowed to complete normally. Any subsequent calls to task.get() will fail with an IllegalStateException. It should be noticed that canceling tasks merely frees up the client side resources. The request may actually be handled normally on the server side. + +
+
+ Callbacks + Instead of manually calling task.get(), you can also use a FutureCallback instance that gets callbacks when the request completes. This is the + same interface as is used in HttpAsyncClient + { + + public void failed(final Exception ex) { + // do something + } + + public void completed(final Boolean result) { + // do something + } + + public void cancelled() { + // do something + } +} + +HttpRequestFutureTask task = futureRequestExecutionService.execute( + new HttpGet("http://www.google.com"), HttpClientContext.create(), + new OkidokiHandler(), new MyCallback()); +]]> +
+
+ Metrics + FutureRequestExecutionService is typically used in applications that make large amounts of + web service calls. To facilitate e.g. monitoring or configuration tuning, the FutureRequestExecutionService keeps + track of several metrics. + Each HttpRequestFutureTask provides methods to get the time the task was scheduled, + started, and ended. Additionally, request and task duration are available as well. These + metrics are aggregated in the FutureRequestExecutionService in a FutureRequestExecutionMetrics + instance that may be accessed through FutureRequestExecutionService.metrics(). +
diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 565db83af..06a02c190 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -36,6 +36,10 @@ Jonathan Moore + + Jilles + van Gurp +