For the latest stable version, please use Spring Integration 6.4.1!

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 Apache Tomcat or Jetty. The easiest way to do this is to use Spring’s HttpRequestHandlerServlet, by providing the following servlet definition in the web.xml file:

<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 Web MVC framework, which is part of the Spring Framework Reference documentation.

For a sample application and the corresponding configuration, see the Spring Integration Samples repository. It contains the HTTP sample application, which demonstrates Spring Integration’s HTTP support.

The following example bean defines an HTTP inbound endpoint:

<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 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.

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 Spring Reference Manual.

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:

<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:

<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.

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 Error Handling.