Timeout Handling

In the context of HTTP components, there are two timing areas that have to be considered:

Timeouts when interacting with Spring Integration Channels
Timeouts when interacting with a remote HTTP server

The components interact with message channels, for which timeouts can be specified. For example, an HTTP Inbound Gateway forwards messages received from connected HTTP Clients to a message channel (which uses a request timeout) and consequently the HTTP Inbound Gateway receives a reply message from the reply channel (which uses a reply timeout) that is used to generate the HTTP Response. The following illustration offers a visual explanation:

Figure 1. How timeout settings apply to an HTTP Inbound Gateway

For outbound endpoints, we need to consider how timing works while interacting with the remote server. The following image shows this scenario:

Figure 2. How timeout settings apply to an HTTP Outbound Gateway

You may want to configure the HTTP related timeout behavior, when making active HTTP requests by using the HTTP outbound gateway or the HTTP outbound channel adapter. In those instances, these two components use Spring’s RestTemplate support to execute HTTP requests.

To configure timeouts for the HTTP outbound gateway and the HTTP outbound channel adapter, you can either reference a RestTemplate bean directly (by using the rest-template attribute) or you can provide a reference to a ClientHttpRequestFactory bean (by using the request-factory attribute). Spring provides the following implementations of the ClientHttpRequestFactory interface:

SimpleClientHttpRequestFactory: Uses standard J2SE facilities for making HTTP Requests
HttpComponentsClientHttpRequestFactory: Uses Apache HttpComponents HttpClient (since Spring 3.1)

If you do not explicitly configure the request-factory or rest-template attribute, a default RestTemplate (which uses a SimpleClientHttpRequestFactory) is instantiated.

With some JVM implementations, the handling of timeouts by the URLConnection class may not be consistent.

For example, from the Java™ Platform, Standard Edition 6 API Specification on setConnectTimeout:

Some non-standard implementation of this method may ignore the specified timeout. To see the connect timeout set, please call getConnectTimeout().

If you have specific needs, you should test your timeouts. Consider using the HttpComponentsClientHttpRequestFactory, which, in turn, uses Apache HttpComponents HttpClient rather than relying on implementations provided by a JVM.

When you use the Apache HttpComponents HttpClient with a pooling connection manager, you should be aware that, by default, the connection manager creates no more than two concurrent connections per given route and no more than 20 connections in total. For many real-world applications, these limits may prove to be too constraining. See the Apache documentation for information about configuring this important component.

The following example configures an HTTP outbound gateway by using a SimpleClientHttpRequestFactory that is configured with connect and read timeouts of 5 seconds, respectively:

<int-http:outbound-gateway url="https://samples.openweathermap.org/data/2.5/weather?q={city}"
                           http-method="GET"
                           expected-response-type="java.lang.String"
                           request-factory="requestFactory"
                           request-channel="requestChannel"
                           reply-channel="replyChannel">
    <int-http:uri-variable name="city" expression="payload"/>
</int-http:outbound-gateway>

<bean id="requestFactory"
      class="org.springframework.http.client.SimpleClientHttpRequestFactory">
    <property name="connectTimeout" value="5000"/>
    <property name="readTimeout"    value="5000"/>
</bean>

HTTP Outbound Gateway

For the HTTP Outbound Gateway, the XML Schema defines only the reply-timeout. The reply-timeout maps to the sendTimeout property of the org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler class. More precisely, the property is set on the extended AbstractReplyProducingMessageHandler class, which ultimately sets the property on the MessagingTemplate.

The value of the sendTimeout property defaults to 30 seconds and will be applied to the connected MessageChannel. This means, that depending on the implementation, the Message Channel’s send method may block indefinitely. Furthermore, the sendTimeout property is only used, when the actual MessageChannel implementation has a blocking send (such as 'full' bounded QueueChannel).

HTTP Inbound Gateway

For the HTTP inbound gateway, the XML Schema defines the request-timeout attribute, which is used to set the requestTimeout property on the HttpRequestHandlingMessagingGateway class (on the extended MessagingGatewaySupport class). You can also use the reply-timeout attribute to map to the replyTimeout property on the same class.

The default for both timeout properties is 1000ms (one thousand milliseconds or one second). Ultimately, the request-timeout property is used to set the sendTimeout on the MessagingTemplate instance. The replyTimeout property, on the other hand, is used to set the receiveTimeout property on the MessagingTemplate instance.

To simulate connection timeouts, you can connect to a non-routable IP address, such as 10.255.255.10.