1. Overview
In this article we will go over the basics of connection management within the HttpClient 4.
We’ll cover the use of BasichttpClientConnectionManager and PoolingHttpClientConnectionManager to enforce a safe, protocol compliant and efficient use of HTTP connections.
2. The BasicHttpClientConnectionManager for a Low Level, Single Threaded Connection
The BasicHttpClientConnectionManager is available since HttpClient 4.3.3 as the simplest implementation of an http connection manager. It is used to create and manage a single connection that can only be used by one thread at a time.
Example 2.1. Getting a Connection Request for a Low Level Connection (HttpClientConnection)
BasicHttpClientConnectionManager connManager =
new BasicHttpClientConnectionManager();
HttpRoute route = new HttpRoute(new HttpHost("www.baeldung.com", 80));
ConnectionRequest connRequest = connManager.requestConnection(route, null);
The requestConnection method gets from the manager a pool of connections for a specific route to connect to. The route parameter specifies a route of “proxy hops” to the target host, or the target host itself.
It is possible to execute a request using an HttpClientConnection directly, but keep in mind this low level approach is verbose and difficult to manage. Low level connections are useful to access socket and connection data such as timeouts and target host information, but for standard executions, the HttpClient is a much easier API to work against.
3. Using the PoolingHttpClientConnectionManager to Get and Manage a Pool of Multithreaded Connections
The PoolingHttpClientConnectionManager will create and manage a pool of connections for each route or target host we use. The default size of the pool of concurrent connections that can be open by the manager is 2 for each route or target host, and 20 for total open connections. First – let’s take a look at how to set up this connection manager on a simple HttpClient: Example 3.1. Setting the PoolingHttpClientConnectionManager on a HttpClient
HttpClientConnectionManager poolingConnManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client = HttpClients.custom().setConnectionManager(poolingConnManager).build();
client.execute(new HttpGet("http://www.baeldung.com/"));
assertTrue(poolingConnManager.getTotalStats().getLeased() == 1);
Next – let’s see how the same connection manager can be used by two HttpClients running in two different threads:
Example 3.2. Using Two HttpClients to Connect to One Target Host Each
HttpGet get1 = new HttpGet("http://www.baeldung.com/");
HttpGet get2 = new HttpGet("http://google.com");
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client1 = HttpClients.custom().setConnectionManager
(connManager).build();
CloseableHttpClient client2 = HttpClients.custom().setConnectionManager
(connManager).build();
MultiHttpClientConnThread thread1 = new MultiHttpClientConnThread(client1, get1);
MultiHttpClientConnThread thread2 = new MultiHttpClientConnThread(client2, get2);
thread1.start();
thread2.start();
thread1.join();
thread2.join();
Notice that we’re using a very simple custom thread implementation – here it is:
Example 3.3. Custom Thread Executing a GET Request
public class MultiHttpClientConnThread extends Thread {
private CloseableHttpClient client;
private HttpGet get;
public MultiHttpClientConnThread(CloseableHttpClient client, HttpGet get) {
this.client = client;
this.get = get;
}
public void run(){
try {
HttpResponse response = client.execute(get);
EntityUtils.consume(response.getEntity());
} catch (ClientProtocolException ex) {
} catch (IOException ex) {
}
}
}
Notice the EntityUtils.consume(response.getEntity) call – necessary to consume the entire content of the response (entity) so that the manager can release the connection back to the pool.
4. Configure the Connection Manager
The defaults of the pooling connection manager are well chosen but – depending on your usecase – may be to small. So – let’s take a look at how we can configure:
- the total number of connections
- the maximum number of connections per (any) route
- the maximum number of connections per a single, specific route
Example 4.1. Increasing the the Number of Connections that Can be Open and Managed Beyond the default Limits
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
connManager.setMaxTotal(5);
connManager.setDefaultMaxPerRoute(4);
HttpHost host = new HttpHost("www.baeldung.com", 80);
connManager.setMaxPerRoute(new HttpRoute(host), 5);
Let’s recap the API:
- setMaxTotal(int max): Set the maximum number of total open connections.
- setDefaultMaxPerRoute(int max): Set the maximum number of concurrent connections per route, which is 2 by default.
- setMaxPerRoute(int max): Set the total number of concurrent connections to a specific route, which is 2 by default.
So, without changing the default, we’re going to reach the limits of the connection manager quite easily – let’s see how that looks like:
Example 4.2. Using Threads to Execute Connections
HttpGet get = new HttpGet("http://www.baeldung.com");
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client = HttpClients.custom().
setConnectionManager(connManager).build();
MultiHttpClientConnThread thread1 = new MultiHttpClientConnThread(client, get);
MultiHttpClientConnThread thread2 = new MultiHttpClientConnThread(client, get);
MultiHttpClientConnThread thread3 = new MultiHttpClientConnThread(client, get);
thread1.start();
thread2.start();
thread3.start();
thread1.join();
thread2.join();
thread3.join();
As we’ve already discussed, the per host connection limit is 2 by default. So, in this example, we’re trying to have 3 threads make 3 requests to the same host, but only 2 connections will be allocated in parallel.
Let’s take a look at the logs – we have three threads running but only 2 leased connections:
[Thread-0] INFO o.b.h.c.MultiHttpClientConnThread - Before - Leased Connections = 0 [Thread-1] INFO o.b.h.c.MultiHttpClientConnThread - Before - Leased Connections = 0 [Thread-2] INFO o.b.h.c.MultiHttpClientConnThread - Before - Leased Connections = 0 [Thread-2] INFO o.b.h.c.MultiHttpClientConnThread - After - Leased Connections = 2 [Thread-0] INFO o.b.h.c.MultiHttpClientConnThread - After - Leased Connections = 2
5. Connection Keep Alive Strategy
Quoting the HttpClient 4.3.3. reference: “If the Keep-Alive header is not present in the response, HttpClient assumes the connection can be kept alive indefinitely.” (See the HttpClient Reference).
To get around this, and be able to mange dead connections we need a customized strategy implementation and build it into the HttpClient.
Example 5.1. A Custom Keep Alive Strategy
ConnectionKeepAliveStrategy myStrategy = new ConnectionKeepAliveStrategy() {
@Override
public long getKeepAliveDuration(HttpResponse response, HttpContext context) {
HeaderElementIterator it = new BasicHeaderElementIterator
(response.headerIterator(HTTP.CONN_KEEP_ALIVE));
while (it.hasNext()) {
HeaderElement he = it.nextElement();
String param = he.getName();
String value = he.getValue();
if (value != null && param.equalsIgnoreCase
("timeout")) {
return Long.parseLong(value) * 1000;
}
}
return 5 * 1000;
}
};
This strategy will first try to apply the host’s Keep-Alive policy stated in the header. If that information is not present in the response header it will keep alive connections for 5 seconds.
Now – let’s create create a client with this custom strategy:
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client = HttpClients.custom().setKeepAliveStrategy(myStrategy).
setConnectionManager(connManager).build();
6. Connection Persistence / Re-Use
The HTTP/1.1 Spec states that connections can be re-used if they have not been closed – this is known as connection persistence.
Once a connection is released by the manager it stays open for re-use. When using a BasicHttpClientConnectionManager, which can only mange a single connection, the connection must be released before it is leased back again:
Example 6.1. BasicHttpClientConnectionManager Connection Re-use
BasicHttpClientConnectionManager basicConnManager =
new BasicHttpClientConnectionManager();
HttpClientContext context = HttpClientContext.create();
// low level
HttpRoute route = new HttpRoute(new HttpHost("www.baeldung.com", 80));
ConnectionRequest connRequest = basicConnManager.requestConnection(route, null);
HttpClientConnection conn = connRequest.get(10, TimeUnit.SECONDS);
basicConnManager.connect(conn, route, 1000, context);
basicConnManager.routeComplete(conn, route, context);
HttpRequestExecutor exeRequest = new HttpRequestExecutor();
context.setTargetHost((new HttpHost("www.baeldung.com", 80)));
HttpGet get = new HttpGet("http://www.baeldung.com");
exeRequest.execute(get, conn, context);
basicConnManager.releaseConnection(conn, null, 1, TimeUnit.SECONDS);
// high level
CloseableHttpClient client = HttpClients.custom().setConnectionManager(basicConnManager).build();
client.execute(get);
Let’s take a look at what happens. First – notice that we’re using a low level connection first, just so that we have full control over when the connection gets released, then a normal higher level connection with a HttpClient. The complex low level logic is not very relevant here – the only thing we care about is the releaseConnection call. That releases the only available connection and allows it to be reused. Then, the client executes the GET request again with success. If we skip releasing the connection, we will get an IllegalStateException from the HttpClient:
java.lang.IllegalStateException: Connection is still allocated
at o.a.h.u.Asserts.check(Asserts.java:34)
at o.a.h.i.c.BasicHttpClientConnectionManager.getConnection
(BasicHttpClientConnectionManager.java:248)
Note that the existing connection isn’t closed, just released and then re-used by the second request.
In contrast to the above example, The PoolingHttpClientConnectionManager allows connection re-use transparently without the need to release a connection implicitly:
Example 6.2. PoolingHttpClientConnectionManager: Re-Using Connections with Threads
HttpGet get = new HttpGet("http://echo.200please.com");
PoolingHttpClientConnectionManager connManager = new
PoolingHttpClientConnectionManager();
connManager.setDefaultMaxPerRoute(5);
connManager.setMaxTotal(5);
CloseableHttpClient client = HttpClients.custom().
setConnectionManager(connManager).build();
MultiHttpClientConnThread[] threads = new MultiHttpClientConnThread[10];
for(int i = 0; i < threads.length; i++){
threads[i] = new MultiHttpClientConnThread(client, get, connManager);
}
for (MultiHttpClientConnThread thread: threads) {
thread.start();
}
for (MultiHttpClientConnThread thread: threads) {
thread.join(1000);
}
The example above has 10 threads, executing 10 requests but only sharing 5 connections. Of course this example relies on the server’s Keep-Alive timeout. To make sure the connections don’t die before being re-used it is recommended to configure the client with a Keep-Alive strategy (See Example 5.1.).
7. Configuring Timeouts – Configuring Socket Timeout Using Connection Manager
The only timeout that can be set at the time when connection manager is configured is the socket timeout:
Example 7.1. Setting Socket Timeout to 5 Seconds
HttpRoute route = new HttpRoute(new HttpHost("www.baeldung.com", 80));
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
connManager.setSocketConfig(route.getTargetHost(),SocketConfig.custom().
setSoTimeout(5000).build());
For a more in-depth discussion of timeouts in the HttpClient – see this.
8. Connection Eviction
Connection eviction is used to detect idle and expired connections and close them; there are two options to do this.
- Relying on the HttpClient to check if the connection is stale before executing a request. This is an expensive option that is not always reliable.
- Create a monitor thread to close idle and/or closed connections.
Example 8.1. Setting the HttpClient to Check for Stale Connections
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client = HttpClients.custom().setDefaultRequestConfig(
RequestConfig.custom().setStaleConnectionCheckEnabled(true).build()).
setConnectionManager(connManager).build();
Example 8.2. Using a Stale Connection Monitor Thread
PoolingHttpClientConnectionManager connManager = new PoolingHttpClientConnectionManager(); CloseableHttpClient client = HttpClients.custom().setConnectionManager(connManager).build(); IdleConnectionMonitorThread staleMonitor = new IdleConnectionMonitorThread(connManager); staleMonitor.start(); staleMonitor.join(1000);
The IdleConnectionMonitorThread class is listed below:
public class IdleConnectionMonitorThread extends Thread {
private final HttpClientConnectionManager connMgr;
private volatile boolean shutdown;
public IdleConnectionMonitorThread
(PoolingHttpClientConnectionManager connMgr) {
super();
this.connMgr = connMgr;
}
@Override
public void run() {
try {
while (!shutdown) {
synchronized (this) {
wait(1000);
connMgr.closeExpiredConnections();
connMgr.closeIdleConnections(30, TimeUnit.SECONDS);
}
}
} catch (InterruptedException ex) {
shutdown();
}
}
public void shutdown() {
shutdown = true;
synchronized (this) {
notifyAll();
}
}
}
9. Connection Closing
A connection can be closed gracefully (an attempt to flush the output buffer prior to closing is made), or forcefully, by calling the shutdown method (the output buffer is not flushed). To properly close connections we need to do all of the following:
- consume and close the response (if closeable)
- close the client
- close and shut down the connection manager
Example 8.1. Closing Connection and Releasing Resources
connManager = new PoolingHttpClientConnectionManager();
CloseableHttpClient client = HttpClients.custom().setConnectionManager(connManager).build();
HttpGet get = new HttpGet("http://google.com");
CloseableHttpResponse response = client.execute(get);
EntityUtils.consume(response.getEntity());
response.close();
client.close();
connManager.close();
connManager.shutdown();
If the manager is shut down without connections being closed already – all connections will be closed and all resources released. It’s important to keep in mind that this will not flush any data that may have been ongoing in the existing connections.
10. Conclusion
In this article we discussed how to use the HTTP Connection Management API of HttpClient to handle the entire process of managing connections – from opening and allocating them, through managing their concurrent use by multiple agents, to finally closing them.
We saw how the BasicHttpClientConnectionManager is a simple solution to handle single connections, and how it can manage low level connections. We also saw how the PoolingHttpClientConnectionManager combined with the HttpClient API provide for an efficient and protocol compliant uses of HTTP connections.