[[http-inbound]]
= Http Inbound Components

To receive messages over HTTP, you need to use an HTTP inbound channel adapter or an HTTP inbound gateway.
To support the HTTP inbound adapters, they need to be deployed within a servlet container such as https://tomcat.apache.org/[Apache Tomcat] or https://www.eclipse.org/jetty/[Jetty].
The easiest way to do this is to use Spring's https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/context/support/HttpRequestHandlerServlet.html[`HttpRequestHandlerServlet`], by providing the following servlet definition in the `web.xml` file:

[source,xml]
----
<servlet>
    <servlet-name>inboundGateway</servlet-name>
    <servlet-class>o.s.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>
----

Notice that the servlet name matches the bean name.
For more information see the `HttpRequestHandlerServlet` Javadocs.

If you are running within a Spring MVC application, then the aforementioned explicit servlet definition is not necessary.
In that case, the bean name for your gateway can be matched against the URL path as you would for a Spring MVC Controller bean.
For more information, see
https://docs.spring.io/spring-framework/reference/web/webmvc.html[Web MVC framework], which is part of the Spring Framework Reference documentation.

TIP: For a sample application and the corresponding configuration, see the https://github.com/spring-projects/spring-integration-samples[Spring Integration Samples] repository.
It contains the https://github.com/spring-projects/spring-integration-samples/tree/main/basic/http[HTTP sample] application, which demonstrates Spring Integration's HTTP support.

The following example bean defines an HTTP inbound endpoint:

[source,xml]
----
<bean id="httpInbound"
  class="org.springframework.integration.http.inbound.HttpRequestHandlingMessagingGateway">
  <property name="requestChannel" ref="httpRequestChannel" />
  <property name="replyChannel" ref="httpReplyChannel" />
</bean>
----

The `HttpRequestHandlingMessagingGateway` accepts a list of `HttpMessageConverter` instances or else relies on a default list.
The converters allow customization of the mapping from `HttpServletRequest` to `Message`.
The default converters encapsulate simple strategies, which (for example) create a `String` message for a `POST` request where the content type starts with `text`.
See the https://docs.spring.io/spring-integration/api/index.html[Javadoc] for full details.
An additional flag (`mergeWithDefaultConverters`) can be set along with the list of custom `HttpMessageConverter` to add the default converters after the custom converters.
By default, this flag is set to `false`, meaning that the custom converters replace the default list.

The message conversion process uses the (optional) `requestPayloadType` property and the incoming `Content-Type` header.
Starting with version 4.3, if a request has no content type header, `application/octet-stream` is assumed, as recommended by `RFC 2616`.
Previously, the body of such messages was ignored.

Spring Integration 2.0 implemented multipart file support.
If the request has been wrapped as a `MultipartHttpServletRequest`, when you use the default converters, that request is converted to a `Message` payload that is a `MultiValueMap` containing values that may be byte arrays, strings, or instances of Spring's `MultipartFile`, depending on the content type of the individual parts.

NOTE: The HTTP inbound endpoint locates a `MultipartResolver` in the context if one has a bean name of `multipartResolver` (the same name expected by Spring's `DispatcherServlet`).
If it does locate that bean, the support for multipart files is enabled on the inbound request mapper.
Otherwise, it fails when it tries to map a multipart file request to a Spring Integration `Message`.
For more on Spring's support for `MultipartResolver`, see the https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-servlet/multipart.html[Spring Reference Manual].

[NOTE]
====
If you wish to proxy a `multipart/form-data` to another server, it may be better to keep it in raw form.
To handle this situation, do not add the `multipartResolver` bean to the context.
Configure the endpoint to expect a `byte[]` request, customize the message converters to include a `ByteArrayHttpMessageConverter`, and disable the default multipart converter.
You may need some other converters for the replies.
The following example shows such an arrangement:

[source, xml]
----
<int-http:inbound-gateway
                  channel="receiveChannel"
                  path="/inboundAdapter.htm"
                  request-payload-type="byte[]"
                  message-converters="converters"
                  merge-with-default-converters="false"
                  supported-methods="POST" />

<util:list id="converters">
    <beans:bean class="org.springframework.http.converter.ByteArrayHttpMessageConverter" />
    <beans:bean class="org.springframework.http.converter.StringHttpMessageConverter" />
    <beans:bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter" />
</util:list>
----
====

When you send a response to the client, you have a number of ways to customize the behavior of the gateway.
By default, the gateway acknowledges that the request was received by sending a `200` status code back.
It is possible to customize this response by providing a 'viewName' to be resolved by the Spring MVC `ViewResolver`.
If the gateway should expect a reply to the `Message`, you can set the `expectReply` flag (constructor argument) to cause the gateway to wait for a reply `Message` before creating an HTTP response.
The following example configures a gateway to serve as a Spring MVC Controller with a view name:

[source,xml]
----
<bean id="httpInbound"
  class="org.springframework.integration.http.inbound.HttpRequestHandlingController">
  <constructor-arg value="true" /> <!-- indicates that a reply is expected -->
  <property name="requestChannel" ref="httpRequestChannel" />
  <property name="replyChannel" ref="httpReplyChannel" />
  <property name="viewName" value="jsonView" />
  <property name="supportedMethodNames" >
    <list>
      <value>GET</value>
      <value>DELETE</value>
    </list>
  </property>
</bean>
----

Because of the `constructor-arg` value of `true`, it waits for a reply.
The preceding example also shows how to customize the HTTP methods accepted by the gateway, which are `POST` and `GET` by default.

The reply message is available in the model map.
By default, the key for that map entry is 'reply', but you can override this default by setting the 'replyKey' property on the endpoint's configuration.

[[http-validation]]
== Payload Validation

Starting with version 5.2, the HTTP inbound endpoints can be supplied with a `Validator` to check a payload before sending into the channel.
This payload is already a result of conversion and extraction after `payloadExpression` to narrow a validation scope in regard to the valuable data.
The validation failure handling is fully the same what we have in Spring MVC https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-servlet/exceptionhandlers.html[Error Handling].

