[[http-outbound]]
= HTTP Outbound Components

This section describes Spring Integration's HTTP outbound components.

[[using-httprequestexecutingmessagehandler]]
== Using `HttpRequestExecutingMessageHandler`

To configure the `HttpRequestExecutingMessageHandler`, write a bean definition similar to the following:

[source,xml]
----
<bean id="httpOutbound"
  class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
  <constructor-arg value="http://localhost:8080/example" />
  <property name="outputChannel" ref="responseChannel" />
</bean>
----

This bean definition runs HTTP requests by delegating to a `RestTemplate`.
That template, in turn, delegates to a list of `HttpMessageConverter` instances to generate the HTTP request body from the `Message` payload.
You can configure those converters as well as the `ClientHttpRequestFactory` instance to use, as the following example shows:

[source,xml]
----
<bean id="httpOutbound"
  class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler">
  <constructor-arg value="http://localhost:8080/example" />
  <property name="outputChannel" ref="responseChannel" />
  <property name="messageConverters" ref="messageConverterList" />
  <property name="requestFactory" ref="customRequestFactory" />
</bean>
----

By default, the HTTP request is generated by using an instance of `SimpleClientHttpRequestFactory`, which uses the JDK `HttpURLConnection`.
Use of the Apache Commons HTTP Client is also supported through `CommonsClientHttpRequestFactory`, which you can inject (as shown earlier).

NOTE: For the outbound gateway, the reply message produced by the gateway contains all the message headers that are present in the request message.

[[using-cookies]]
== Using Cookies

Basic cookie support is provided by the `transfer-cookies` attribute on the outbound gateway.
When set to `true` (the default is `false`), a `Set-Cookie` header received from the server in a response is converted to `Cookie` in the reply message.
This header is then used on subsequent sends.
This enables simple stateful interactions, such as the following:

`...->logonGateway->...->doWorkGateway->...->logoffGateway->...`

If `transfer-cookies` is `false`, any `Set-Cookie` header received remains as `Set-Cookie` in the reply message and is dropped on subsequent sends.

[NOTE]
.Empty Response Bodies
=====
HTTP is a request-response protocol.
However, the response may not have a body, only headers.
In this case, the `HttpRequestExecutingMessageHandler` produces a reply `Message` with the payload being an `org.springframework.http.ResponseEntity`, regardless of any provided `expected-response-type`.
According to the https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[HTTP RFC Status Code Definitions], there are many statuses that mandate that a response must not contain a message-body (for example, `204 No Content`).
There are also cases where calls to the same URL might or might not return a response body.
For example, the first request to an HTTP resource returns content, but the second does not (returning a `304 Not Modified`).
In all cases, however, the `http_statusCode` message header is populated.
This can be used in some routing logic after the HTTP outbound gateway.
You could also use a`<payload-type-router/>` to route messages with a `ResponseEntity` to a different flow than that used for responses with a body.
=====
[NOTE]
.expected-response-type
=====
Further to the preceding note about empty response bodies, if a response does contain a body, you must provide an appropriate `expected-response-type` attribute or, again, you receive a `ResponseEntity` with no body.
The `expected-response-type` must be compatible with the (configured or default) `HttpMessageConverter` instances and the `Content-Type` header in the response.
This can be an abstract class or even an interface (such as `java.io.Serializable` when you use Java serialization and `Content-Type: application/x-java-serialized-object`).
=====

Starting with version 5.5, the `HttpRequestExecutingMessageHandler` exposes an `extractResponseBody` flag (which is `true` by default) to return just the response body, or to return the whole `ResponseEntity` as the reply message payload, independently of the provided `expectedResponseType`.
If a body is not present in the `ResponseEntity`, this flag is ignored and the whole `ResponseEntity` is returned.

