HttpClient is one of the most versatile Java libraries. Unfortunately, it comes with a lot of configuration options that may be way too cryptic or difficult. While the API for 4.x series has been significantly improved there are still some sharp edges.

The deprecated or 3.x way of setting the timeout.

This is done using params. Note that this is still 4.x code but a deprecated one

DefaultHttpClient httpClient = ...;
   
HttpParams httpParams = httpClient.getParams();
httpParams.setParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 1000L);
httpParams.setParameter(CoreConnectionPNames.SO_TIMEOUT, 1000L);
httpParams.setParameter(ClientPNames.CONN_MANAGER_TIMEOUT, 1000L);

Now the part httpClient.getParams() is deprecated since obviously this is a nasty API. You need to keep track of parameters with Enums/constants and their type as well.

The right 4.x way aka the builder way

HttpClient 4 is full of builder for everything. While I often love the Builder patterns in some cases the testing part is really difficult but I guess it is always a tradeoff. This would be the "right way".

public RequestConfig requestConfigWithTimeout(int timeoutInMilliseconds) {
        return RequestConfig.copy(RequestConfig.DEFAULT)
                .setSocketTimeout(timeoutInMilliseconds)
                .setConnectTimeout(timeoutInMilliseconds)
                .setConnectionRequestTimeout(timeoutInMilliseconds)
                .build();
}

The meaning of the parameters

Notice that we are actually setting 3 different timeouts.

• Socket Timeout - this is the time of inactivity to wait for packets to arrive
• Connection Timeout - the time to establish a connection with the remote host
• Connection Manager Timeout - the time to fetch a connection from the connection pool

The third one costed me dearly, it wasn't until the client was under a high load that issues started happening. The connection pool I was using had 10 connections per route limitation set and the scenario was quite common. As you can see these settings do not provide a mechanism for making an N millisecond hard timeout.

If we were to setup the timeout to 10 seconds on each of this we could end up with a request that lasts 9(sec to get a connection) + 9( sec to open connection ) + 9( sec of inactivity ) = 28 sec.

More info

A bug when setting the ConnectionRequestTimeout
The RequestConfig Javadoc
Apache HttpClient examples