HttpClient Connection Management

I just announced the new Spring 5 modules in REST With Spring:

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.

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

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:

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:

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:

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 – Socket Timeout Using The Connection Manager

The only timeout that can be set at the time when connection manager is configured is the socket timeout:

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 for 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.

I just announced the new Spring 5 modules in REST With Spring:

Hi, I am new to HttpClient lib and working on an existing framework which is on HttpClient 3.x version. Would you please tell me what benifits PoolledConnectionManager offers over ThreadSafeClientConnManager ?

You Must Be Logged In To Vote0You Must Be Logged In To Vote

4 years ago

Guest

Elena Eidson

Hey Sachin, The ThreadSafeClientConnManager has been deprecated, and you should use the PoolingHttpClientConnectionManager instead.

You Must Be Logged In To Vote0You Must Be Logged In To Vote

4 years ago

Guest

Kisna

How is poolinghttpclientconnectionmanager different from poolingclientconnectionmanager?

Hey Kisna – the difference between the two is simply that the first is now deprecated by the second. There were a lot of API changes between 4.2 and 4.3, and the introduction of some builders, more fluent utilities, etc in 4.3, and so, if you’re using 4.3 (or 4.4), it’s a good idea to use the PoolingHttpClientConnectionManager. Also – the deprecated versions are removed sooner or later – which is another reason to go with the non-deprecated version. Other than that – they’re quite similar.

You Must Be Logged In To Vote0You Must Be Logged In To Vote

3 years ago

Guest

Kisna

Thanks so much, could not figure out if we really needed it for better performance or not

You Must Be Logged In To Vote0You Must Be Logged In To Vote

3 years ago

Guest

Kisna

One more: does httpclient socket connection pooling benefit from massive retrieval of resources such as, say, images/files from CDN as they are all resource GETs from same client host to the same CDN host? especially given CDN will resolve to an optimized server (from many) based on location, availability, and other metrics and that server will handle the request?

Hey Kisna – that’s going to vary widely from case to case. My suggestion is – don’t try to make a determination based on general things about the client. Instead – test it out. You can use Jmeter (it delegates to HttpClient) or you can orchestrate your own test – but do a proper test and see how much of a difference it makes. Hope that helps. Cheers,
Eugen.

You Must Be Logged In To Vote0You Must Be Logged In To Vote

3 years ago

Guest

Subhash Sreeram

Can I benefit from PoolingHttpClientManager if multiple threads are connecting to same route. But calling different service:

You can definitely make good use of the pooling manager regardless of the fact that you’re connecting to the same host or not.

You Must Be Logged In To Vote0You Must Be Logged In To Vote

3 years ago

Guest

Kisna

One more :), do both PoolingClientConnectionManagers enable KeepAlive by default, because, I would assume the other side of client would want to terminate such long living connections abruptly most of the time or do this connection manager do some sort of a sanity check if connections are alive routinely and terminate/recycle them if it sees any issue? Is there any related configuration/settings to manage these times.

The releaseConnection API has a maximum period for which the connection will be kept alive, so it won’t be alive indefinitely. There is also a ConnectionKeepAliveStrategy if you need to fine-tune that behavior for the connection manager. Hope that helps. Cheers,
Eugen.

It should close the connection – the pool has a mechanism responsible with creating new connections when needed.

You Must Be Logged In To Vote0You Must Be Logged In To Vote

3 years ago

Guest

Sanjoy

Hello Eugen, great article, do you recommend closing the response after each execute method, as u say not closing the response will not close the connection and its better for the connection manager, what do you recommend and why ? I was of the impression that closing the response will return the connection to the pool.

So, there are a few different ways to release low level resources. You can either close the content stream – which will keep the connection alive, or you can close the response – which will shut down the connection. So – if your goal is to release the connection back to the pool for reuse, consuming and closing the content stream is the way to go. Here’s an interesting, in-depth exploration of this here. Hope it helps. Cheers,
Eugen.