1. Overview

This tutorial will show how to configure a timeout with the Apache HttpClient 5.

If you want to dig deeper and learn other cool things, you can do with the HttpClient, head on to the main HttpClient tutorial.

2. Configure Timeouts Using the HttpClient 5.x API

The new API version has introduced new ways of configuring the timeouts. We will configure connection timeout and socket timeout by using ConnectionConfig :

ConnectionConfig connConfig = ConnectionConfig.custom()
 .setConnectTimeout(timeout, TimeUnit.MILLISECONDS)
 .setSocketTimeout(timeout, TimeUnit.MILLISECONDS)
 .build();

The next step will be to create a connection manager and set the ConnectionConfig that we created above:

BasicHttpClientConnectionManager cm = new BasicHttpClientConnectionManager();
cm.setConnectionConfig(connConfig);

For detailed examples of configuring connection manager, follow our article Apache HttpClient Connection Management.

3. Configure Timeouts Using the HttpClient 4.3

If we are using HttpClient 4.3, we can use the fluent builder API to set timeouts at a high level:

int timeout = 5;
RequestConfig config = RequestConfig.custom()
 .setConnectTimeout(timeout * 1000)
 .setConnectionRequestTimeout(timeout * 1000)
 .setSocketTimeout(timeout * 1000).build();
CloseableHttpClient client = 
 HttpClientBuilder.create().setDefaultRequestConfig(config).build();

In this way, we can configure all three timeouts in a type-safe and readable manner.

4. Timeout Properties Explained

Now, let’s explain what these various types of timeouts mean:

• the Connection Timeout (http.connection.timeout) – the time to establish the connection with the remote host
• the Socket Timeout (http.socket.timeout) – the time waiting for data – after establishing the connection; maximum time of inactivity between two data packets
• the Connection Manager Timeout (http.connection-manager.timeout) – the time to wait for a connection from the connection manager/pool

The first two parameters – the connection and socket timeouts – are the most important. However, setting a timeout for obtaining a connection is definitely important in high load scenarios, which is why the third parameter shouldn’t be ignored.

5. Using the HttpClient

After configuring it, we can now use the client to perform HTTP requests:

final HttpGet request = new HttpGet("http://www.github.com");

try (CloseableHttpClient client = HttpClientBuilder.create()
 .setDefaultRequestConfig(requestConfig)
 .setConnectionManager(cm)
 .build();

 CloseableHttpResponse response = (CloseableHttpResponse) client
 .execute(request, new CustomHttpClientResponseHandler())) {

 final int statusCode = response.getCode();
 assertThat(statusCode, equalTo(HttpStatus.SC_OK));
}

With the previously defined client, the connection to the host will time out in 5 seconds. Also, if the connection is established, but no data is received, the timeout will also be 5 additional seconds.

Note that the connection timeout will result in an org.apache.hc.client5.http.ConnectTimeoutException being thrown, while socket timeout will result in a java.net.SocketTimeoutException.

6. Hard Timeout

While setting timeouts on establishing the HTTP connection and not receiving data is very useful, sometimes we need to set a hard timeout for the entire request.

For example, the download of a potentially large file fits into this category. In this case, the connection may be successfully established, and data may be consistently coming through, but we still need to ensure that the operation doesn’t go over some specific time threshold.

HttpClient doesn’t have any configuration that allows us to set an overall timeout for a request; it does, however, provide abort functionality for requests, so we can leverage that mechanism to implement a simple timeout mechanism:

HttpGet getMethod = new HttpGet("http://localhost:8082/httpclient-simple/api/bars/1");
getMethod.setConfig(requestConfig);

int hardTimeout = 5000; // milliseconds
TimerTask task = new TimerTask() {
 @Override
 public void run() {
 getMethod.abort();
 }
};
new Timer(true).schedule(task, hardTimeout);

try (CloseableHttpClient client = HttpClientBuilder.create()
 .setDefaultRequestConfig(requestConfig)
 .setConnectionManager(cm)
 .build();

 CloseableHttpResponse response = (CloseableHttpResponse) client
 .execute(getMethod, new CustomHttpClientResponseHandler())) {

 final int statusCode = response.getCode();
 System.out.println("HTTP Status of response: " + statusCode);
 assertThat(statusCode, equalTo(HttpStatus.SC_OK));
}

We’re making use of the java.util.Timer and java.util.TimerTask to set up a simple delayed task which aborts the HTTP GET request after a 5 seconds hard timeout.

7. Timeout and DNS Round Robin – Something to Be Aware Of

It’s quite common for some larger domains to use a DNS round-robin configuration – essentially having the same domain mapped to multiple IP addresses. This introduces a new challenge for a timeout against such a domain simply because of the way HttpClient will try to connect to that domain that times out:

• HttpClient gets the list of IP routes to that domain
• it tries the first one – that times out (with the timeouts we configure)
• it tries the second one – which also times out
• and so on …

So, as you can see – the overall operation will not time out when we expect it to. Instead – it will time out when all the possible routes have timed out. Moreover, this will happen completely transparently for the client (unless you have your log configured at the DEBUG level).

Here’s a simple example you can run and replicate this issue:

ConnectionConfig connConfig = ConnectionConfig.custom()
 .setConnectTimeout(timeout, TimeUnit.MILLISECONDS)
 .setSocketTimeout(timeout, TimeUnit.MILLISECONDS)
 .build();

RequestConfig requestConfig = RequestConfig.custom()
 .setConnectionRequestTimeout(Timeout.ofMilliseconds(3000L))
 .build();

BasicHttpClientConnectionManager cm = new BasicHttpClientConnectionManager();
cm.setConnectionConfig(connConfig);

CloseableHttpClient client = HttpClientBuilder.create()
 .setDefaultRequestConfig(requestConfig)
 .setConnectionManager(cm)
 .build();

HttpGet request = new HttpGet("http://www.google.com:81");

response = client.execute(request, new CustomHttpClientResponseHandler());

You will notice the retrying logic with a DEBUG log level:

DEBUG o.a.h.i.c.HttpClientConnectionOperator - Connecting to www.google.com/173.194.34.212:81
DEBUG o.a.h.i.c.HttpClientConnectionOperator - 
 Connect to www.google.com/173.194.34.212:81 timed out. Connection will be retried using another IP address

DEBUG o.a.h.i.c.HttpClientConnectionOperator - Connecting to www.google.com/173.194.34.208:81
DEBUG o.a.h.i.c.HttpClientConnectionOperator - 
 Connect to www.google.com/173.194.34.208:81 timed out. Connection will be retried using another IP address

DEBUG o.a.h.i.c.HttpClientConnectionOperator - Connecting to www.google.com/173.194.34.209:81
DEBUG o.a.h.i.c.HttpClientConnectionOperator - 
 Connect to www.google.com/173.194.34.209:81 timed out. Connection will be retried using another IP address
//...

8. Conclusion

This tutorial discussed how to configure the various types of timeouts available for an HttpClient. It also illustrated a simple mechanism for the hard timeout of an ongoing HTTP connection.