This document provides an overview of how to use HttpClient safely from within a multi-threaded environment. It is broken down into the following main sections:
Please see the MultiThreadedExample for a concrete example.
The main reason for using multiple theads in HttpClient is to allow the execution of multiple methods at once (Simultaniously downloading the latest builds of HttpClient and Tomcat for example). During execution each method uses an instance of an HttpConnection. Since connections can only be safely used from a single thread and method at a time and are a finite resource, we need to ensure that connections are properly allocated to the methods that require them. This job goes to the MultiThreadedHttpConnectionManager.
To get started one must create an instance of the MultiThreadedHttpConnectionManager and give it to an HttpClient. This looks something like:
MultiThreadedHttpConnectionManager connectionManager =
new MultiThreadedHttpConnectionManager();
HttpClient client = new HttpClient(connectionManager);
This instance of HttpClient can now be used to execute multiple methods from multiple threads. Each subsequent call to HttpClient.executeMethod() will go to the connection manager and ask for an instance of HttpConnection. This connection will be checked out to the method and as a result it must also be returned. More on this below in Connection Release.
The MultiThreadedHttpConnectionManager supports the following options:
| connectionStaleCheckingEnabled | The connectionStaleCheckingEnabled flag to set on all created connections. This value should be left true except in special circumstances. Consult the HttpConnection docs for more detail. |
| maxConnectionsPerHost | The maximum number of connections that will be created for any particular HostConfiguration. Defaults to 2. |
| maxTotalConnections | The maximum number of active connections. Defaults to 20. |
In general the connection manager makes an attempt to reuse connections for a particular host while still allowing different connections to be used simultaneously. Connection are reclaimed using a least recently used approach.
One main side effect of connection management is that connections must be manually released when no longer used. This is due to the fact that HttpClient cannot determine when a method is no longer using its connection. This occurs because a method's response body is not read directly by HttpClient, but by the application using HttpClient. When the response is read it must obviously make use of the method's connection. Thus, a connection cannot be released from a method until the method's response body is read which is after HttpClient finishes executing the method. The application therefore must manually release the connection by calling releaseConnection() on the method after the response body has been read. To safely ensure connection release HttpClient should be used in the following manner:
MultiThreadedHttpConnectionManager connectionManager =
new MultiThreadedHttpConnectionManager();
HttpClient client = new HttpClient(connectionManager);
...
// and then from inside some thread executing a method
GetMethod get = new GetMethod("http://httpcomponents.apache.org/");
try {
client.executeMethod(get);
// print response to stdout
System.out.println(get.getResponseBodyAsStream());
} finally {
// be sure the connection is released back to the connection
// manager
get.releaseConnection();
}
Particularly, notice that the connection is released regardless of what the result of executing the method was or whether or not an exception was thrown. For every call to HttpClient.executeMethod there must be a matching call to method.releaseConnection().