Java HttpClient Connection Management

1. Overview

Our applications often need some form of connection management to better utilize resources.

In this tutorial, we’ll look at what connection management support is available to us in Java 11’s HttpClient. We’ll cover the use of system properties to set pool size and default timeouts, and WireMock to simulate different hosts.

2. Java HttpClient‘s Connection Pool

The Java 11 HttpClient has an internal connection pool. By default, it is unlimited in size.

Let’s see the connection pool in action by building an HttpClient that we can use to send our requests:

HttpClient client = HttpClient.newHttpClient();

3. Target Server

We’ll use WireMock servers as our simulated hosts. That enables us to use Jetty’s debug logging to track which connections are being made.

First, let’s see the HttpClient making and then reusing a cached connection. Let’s start our simulated host by starting up a WireMock server on a dynamic port:

WireMockServer server = new WireMockServer(WireMockConfiguration
  .options()
  .dynamicPort());

In our setup() method, let’s start the server and configure it to respond to any request with a 200 response:

firstServer.start();
server.stubFor(WireMock
  .get(WireMock.anyUrl())
  .willReturn(WireMock
    .aResponse()
    .withStatus(200)));

Next, let’s create the HttpRequest that we’ll send, configured to point to our WireMock endpoint:

HttpRequest getRequest = HttpRequest.newBuilder()
  .uri(create("http://localhost:" + server.port() + "/first";))
  .build();

Now that we have a client and a server to send to, let’s send our request:

HttpResponse<String> response = client.send(getRequest, HttpResponse.BodyHandlers.ofString());

To keep it simple, we used the ofString factory method in the HttpResponse.BodyHandler inner class to create our String response handler.

We don’t see much happen when we run this code, so let’s turn on some debugging to find out whether our connection really does get made and reused.

4. Jetty Debug Logging Configuration

Given the sparsity of logging in JDK 11’s ConnectionPool class, we’ll need external logging to help us see when connections are reused or created.

So let’s enable Jetty’s debug logging by creating a jetty-logging.properties in our classpath:

org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StrErrLog
org.eclipse.jetty.LEVEL=DEBUG
jetty.logs=logs

Here, we’ve set Jetty’s logging level to DEBUG and configured it to write to the error output stream.

When a new connection is created, Jetty logs a “New HTTP Connection” message:

DBUG:oejs.HttpConnection:qtp2037764568-17-selector-ServerConnectorManager@34b9f960/0: New HTTP Connection HttpConnection@ba7665b{IDLE}

We can look for these messages to confirm connection creation activity as we run our tests.

5. Connection Pool – Establishment and Reuse

Now that we have our client, and a server that logs when it is asked for a new connection, we’re ready to run some tests.

First, let’s validate that the HttpClient really does make use of an internal connection pool. If there’s a connection pool in use, we’ll only see a single “New HTTP Connection” message.

So, let’s fire two requests to the same server and see how many new connection messages are logged:

HttpResponse<String> firstResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
HttpResponse<String> secondResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());

Now let’s check the log output for the “New HTTP Connection” message:

DBUG:oejs.HttpConnection:qtp2037764568-17-selector-ServerConnectorManager@34b9f960/0: New HTTP Connection HttpConnection@ba7665b{IDLE}

We see there is only one new connection request logged. This tells us that the second request we made didn’t need to create a new connection.

Our client established a connection and put it in the pool during the first call, allowing the second call to reuse the same connection.

So, now let’s see if the connection pool is unique to a client or is shared across clients.

Let’s create a second client to check:

HttpClient secondClient = HttpClient.newHttpClient();

And let’s send a request to the same server from each of our clients

HttpResponse<String> firstResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
HttpResponse<String> secondResponse = secondClient.send(getRequest, HttpResponse.BodyHandlers.ofString());

When we check the log output, we see not one but two new connections created:

DBUG:oejs.HttpConnection:qtp729218894-17-selector-ServerConnectorManager@51acdf2e/0: New HTTP Connection HttpConnection@3cc85dbb{IDLE}
DBUG:oejs.HttpConnection:qtp729218894-21-selector-ServerConnectorManager@51acdf2e/1: New HTTP Connection HttpConnection@6062141{IDLE}

Our second client caused the creation of a new connection to the same destination. From this, we can deduce that there is a connection pool per client.

6. Controlling the Connection Pool Size

Now that we’ve seen connections being created and reused, let’s see how we can control the pool size.

The JDK 11 ConnectionPool checks the jdk.httpclient.connectionPoolSize system property when initializing and defaults to 0 (unlimited).

We can set system properties as a JVM argument or programmatically. Since this property will only be read on initialization, however, we’ll use JVM arguments to ensure the value is set the first time any connection is made.

First, let’s run a test that first calls one server, then another, and then back to the first again:

HttpResponse<String> firstResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
HttpResponse<String> secondResponse = client.send(secondGet, HttpResponse.BodyHandlers.ofString());
HttpResponse<String> thirdResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());

We see just two connection requests in our logs since our pool still contains the connection made in our first request:

DBUG:oejs.HttpConnection:qtp2037764568-17-selector-ServerConnectorManager@34b9f960/0: New HTTP Connection HttpConnection@1af88cae{IDLE}
DBUG:oejs.HttpConnection:qtp1932332324-26-selector-ServerConnectorManager@13d4992d/0: New HTTP Connection HttpConnection@71c7d4f{IDLE}

Now let’s change this default behavior by setting the pool size to 1:

-Djdk.httpclient.connectionPoolSize=1

We wouldn’t normally set the pool size to 1, but in this case, doing so enables us to reach the maximum pool size more quickly.

When we run the test again with our property set, we see three connections created:

DBUG:oejs.HttpConnection:qtp2104973502-22-selector-ServerConnectorManager@48b67364/0: New HTTP Connection HttpConnection@3da6a47f{IDLE}
DBUG:oejs.HttpConnection:qtp351877391-26-selector-ServerConnectorManager@3b8f0a79/0: New HTTP Connection HttpConnection@20b59486{IDLE}
DBUG:oejs.HttpConnection:qtp2104973502-18-selector-ServerConnectorManager@48b67364/1: New HTTP Connection HttpConnection@599a00c1{IDLE}

Our property had the effect we expected! With a connection pool size of just one, the first connection is purged from the pool when the call to the second server is made. So, when our third call is made back to the first server, there’s no entry in the pool anymore, and we have to create a new third connection.

7. Connection Keepalive Timeouts

Once a connection has been established, it will remain in our pool for reuse. If a connection sits idle for too long, then it will be purged from our connection pool.

The JDK 11 ConnectionPool checks the jdk.httpclient.keepalive.timeout system property when initializing and defaults to 1200 seconds (20 minutes).

Note that the keepalive timeout system property differs from the HttpClient‘s connectTimeout method. Connection timeout determines how long we’ll wait to establish a new connection, whereas keepalive timeout determines how long to keep a connection alive once it’s been established.

Since 20 minutes is a long time in modern architecture, JDK20, build 26 reduces the default to 30 seconds.

Let’s test this setting by reducing it to 2 seconds by setting our keepalive system property via a JVM argument:

-Djdk.httpclient.keepalive.timeout=2

Now let’s run a test that sleeps for enough time for the connection to be dropped between calls:

HttpResponse<String> firstResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
Thread.sleep(3000);
HttpResponse<String> secondResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());

As expected, we see a new connection created for both requests since the first connection was dropped after 2 seconds.

DBUG:oejs.HttpConnection:qtp1889057031-18-selector-ServerConnectorManager@928763c/0: New HTTP Connection HttpConnection@7d1c0d89{IDLE}
DBUG:oejs.HttpConnection:qtp1889057031-20-selector-ServerConnectorManager@928763c/1: New HTTP Connection HttpConnection@62a8bb1d{IDLE}

8. Enhanced HttpClient

The HttpClient has evolved further since JDK 11, such as various networking logging improvements. When we run these tests against Java 19, we can explore the HttpClient‘s internal logs to monitor network activity instead of relying on WireMock’s Jetty logging. There are also some useful recipes for how to use the client.

Since HttpClient also supports HTTP/2 (H2) connections, which use connection multiplexing, our application may not need to use as many connections. So, in JDK20, build 25, some additional system properties were introduced specifically for H2 pools:

• jdk.httpclient.keepalivetimeout.h2 – set this property to control the keepalive timeout for H2 connections
• jdk.httpclient.maxstreams – set this property to control the maximum number of H2 streams that are permitted per HTTP connection (defaults to 100).

9. Conclusion

In this tutorial, we saw how the Java HttpClient reuses connections from its internal connection pool. We used Wiremock with Jetty logging to show us when new connection requests were made. Next, we learned how to control the connection pool size and its effect when the pool limit is reached. We also learned how to configure the time after which our idle connections should be purged.

Finally, we looked at some of the networking changes made in more recent versions of Java.

Our Apache HttpClient4 tutorial demonstrates an alternative to the Java 11 client when we use versions of Java before 11 or need different functionality.