This tutorial will show how to configure a timeout with the Apache HttpClient 4.
If you want to dig deeper and learn other cool things you can do with the HttpClient – head on over to the main HttpClient tutorial.
2. Configure Timeouts via raw String Parameters
The HttpClient comes with a lot of configuration parameters – and all of these can be set in a generic, map-like manner.
There are 3 timeout parameters to configure:
- Android stuido viewpagerindicator的使用
- Intellij IDEA工具Java web 环境搭建
- 公司拷贝回家的工程用sts导入clean package报错java.lang.NoClassDefFoundError
A quick note is that the last parameter – the connection manager timeout – is commented out when using the 4.3.0 or 4.3.1 versions, because of this JIRA (due in 4.3.2).
3. Configure Timeouts via the API
The more important of these parameters – namely the first two – can also be set via a more type safe API:
The third parameter doesn’t have a custom setter in HttpConnectionParams, and it will still need to be set manually via the setParameter method.
4. Configure Timeouts using the new 4.3. Builder
The fluent, builder API introduced in 4.3 provides the right way to set timeouts at a high level:
That is the recommended way of configuring all three timeouts in a type-safe and readable manner.
5. 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 the connection was established; 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, but setting a timeout for obtaining a connection is definitely important in high load scenarios, which is why the third parameter shouldn’t be ignored.
6. Using the HttpClient
After being configured, the client can not be used to perform HTTP requests:
With the previously defined client, the connection to the host will time out in 5 seconds, and 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.http.conn.ConnectTimeoutException being thrown, while socket timeout will result in a java.net.SocketTimeoutException.
7. 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, 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:
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.
8. Timeout and DNS Round Robin – something to be aware of
It is quite common that some larger domains will be using 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 – that 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, and what it more – this will happen completely transparently for the client (unless you have your log configured at the DEBUG level). Here is a simple example you can run and replicate this issue:
You will notice the retrying logic with a DEBUG log level:
This tutorial discussed how to configure the various types of timeouts available for an HttpClient. It also illustrated a simple mechanism for hard timeout of an ongoing HTTP connection.
The implementation of these examples can be found in the GitHub project – this is a Maven-based project, so it should be easy to import and run as it is.