211 lines
13 KiB
XML
211 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="http"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
<title>HTTP Support</title>
|
||
|
||
<section id="http-intro">
|
||
<title>Introduction</title>
|
||
<para>
|
||
The HTTP support allows for the execution of HTTP requests and the processing of inbound HTTP requests. Because interaction over HTTP is always synchronous, even if all that is returned is a 200 status code, the HTTP support consists of two gateway implementations:
|
||
<classname>HttpInboundEndpoint</classname> and <classname>HttpRequestExecutingMessageHandler</classname>.
|
||
</para>
|
||
</section>
|
||
|
||
<section id="http-inbound">
|
||
<title>Http Inbound Gateway</title>
|
||
<para>
|
||
To receive messages over HTTP you need to use an HTTP inbound Channel Adapter or Gateway. In common with the HttpInvoker
|
||
support the HTTP inbound adapters need to be deployed within a servlet container. The easiest way to do this is to provide a servlet
|
||
definition in <emphasis>web.xml</emphasis>, see
|
||
<xref linkend="httpinvoker-inbound"/> for further details. Below is an example bean definition for a simple HTTP inbound endpoint.
|
||
<programlisting language="xml"><![CDATA[<bean id="httpInbound" class="org.springframework.integration.http.inbound.HttpRequestHandlingMessagingGateway">
|
||
<property name="requestChannel" ref="httpRequestChannel" />
|
||
<property name="replyChannel" ref="httpReplyChannel" />
|
||
</bean>]]></programlisting>
|
||
The <classname>HttpRequestHandlingMessagingGateway</classname> accepts a list of <interfacename>HttpMessageConverter</interfacename> instances or else
|
||
relies on a default list. The converters allow
|
||
customization of the mapping from <interfacename>HttpServletRequest</interfacename> to <interfacename>Message</interfacename>. The default converters
|
||
encapsulate simple strategies, which for
|
||
example will create a String message for a <emphasis>POST</emphasis> request where the content type starts with "text", see the Javadoc for
|
||
full details.
|
||
</para>
|
||
<para>Starting with this release MultiPart File support was implemented. If the request has been wrapped as a
|
||
<emphasis>MultipartHttpServletRequest</emphasis>, when using the default converters, that request will be converted
|
||
to a Message payload that is a MultiValueMap containing values that may be byte arrays, Strings, or instances of
|
||
Spring's <interfacename>MultipartFile</interfacename> depending on the content type of the individual parts.
|
||
<note>
|
||
The HTTP inbound Endpoint will locate a MultipartResolver in the context if one exists with the bean name
|
||
"multipartResolver" (the same name expected by Spring's DispatcherServlet). If it does in fact locate that
|
||
bean, then the support for MultipartFiles will be enabled on the inbound request mapper. Otherwise, it will
|
||
fail when trying to map a multipart-file request to a Spring Integration Message. For more on Spring's
|
||
support for MultipartResolvers, refer to the <ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/mvc.html#mvc-multipart">Spring Reference Manual</ulink>.
|
||
</note>
|
||
</para>
|
||
<para>
|
||
In sending a response to the client there are a number of ways to customize the behavior of the gateway. By default the gateway will
|
||
simply acknowledge 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 <interfacename>ViewResolver</interfacename>.
|
||
In the case that the gateway should expect a reply to the <interfacename>Message</interfacename> then setting the <property>expectReply</property> flag
|
||
(constructor argument) will cause
|
||
the gateway to wait for a reply <interfacename>Message</interfacename> before creating an HTTP response. Below is an example of a gateway
|
||
configured to serve as a Spring MVC Controller with a view name. Because of the constructor arg value of TRUE, it wait for a reply. This also shows
|
||
how to customize the HTTP methods accepted by the gateway, which
|
||
are <emphasis>POST</emphasis> and <emphasis>GET</emphasis> by default.
|
||
<programlisting language="xml"><![CDATA[<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>
|
||
<property name="expectReply" value="true" />
|
||
</bean>]]></programlisting>
|
||
The reply message will be available in the Model map. The key that is used
|
||
for that map entry by default is 'reply', but this can be overridden by setting the
|
||
'replyKey' property on the endpoint's configuration.
|
||
</para>
|
||
</section>
|
||
|
||
<section id="http-outbound">
|
||
<title>Http Outbound Gateway</title>
|
||
|
||
<para>
|
||
To configure the <classname>HttpRequestExecutingMessageHandler</classname> write a bean definition like this:
|
||
<programlisting language="xml"><![CDATA[<bean id="httpOutbound" class="org.springframework.integration.http.outbound.HttpRequestExecutingMessageHandler" >
|
||
<constructor-arg value="http://localhost:8080/example" />
|
||
<property name="outputChannel" ref="responseChannel" />
|
||
</bean>]]></programlisting>
|
||
This bean definition will execute HTTP requests by delegating to a <classname>RestTemplate</classname>. That template in turn delegates
|
||
to a list of HttpMessageConverters to generate the HTTP request body from the Message payload. You can configure those converters as well
|
||
as the ClientHttpRequestFactory instance to use:
|
||
<programlisting language="xml"><![CDATA[<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>]]></programlisting>
|
||
By default the HTTP request will be generated using an instance of <classname>SimpleClientHttpRequestFactory</classname> which uses the JDK
|
||
<classname>HttpURLConnection</classname>. Use of the Apache Commons HTTP Client is also supported through the provided
|
||
<classname>CommonsClientHttpRequestFactory</classname> which can be injected as shown above.
|
||
</para>
|
||
</section>
|
||
|
||
<section id="http-namespace">
|
||
<title>HTTP Namespace Support</title>
|
||
<para>
|
||
Spring Integration provides an "http" namespace and schema definition. To include it in your
|
||
configuration, simply provide the following URI within a namespace declaration:
|
||
'http://www.springframework.org/schema/integration/http'. The schema location should then map to
|
||
'http://www.springframework.org/schema/integration/http/spring-integration-http.xsd'.
|
||
</para>
|
||
<para>
|
||
To configure an inbound http channel adapter which is an instance of <classname>HttpInboundEndpoint</classname> configured
|
||
not to expect a response.
|
||
<programlisting language="xml"><![CDATA[ <http:inbound-channel-adapter id="httpChannelAdapter" channel="requests" supported-methods="PUT, DELETE"/>]]></programlisting>
|
||
</para>
|
||
<para>
|
||
To configure an inbound http gateway which expects a response.
|
||
<programlisting language="xml"><![CDATA[ <http:inbound-gateway id="inboundGateway" request-channel="requests" reply-channel="responses"/>]]></programlisting>
|
||
</para>
|
||
<para>
|
||
To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration options for an outbound Http gateway. Most importantly, notice that the 'http-method' and 'expected-response-type' are provided. Those are two of the most commonly configured values. The
|
||
default http-method is POST, and the default response type is <emphasis>null</emphasis>. With a null response type, the payload of the reply Message would only
|
||
contain the status code (e.g. 200) as long as it's a successful status (non-successful status codes will throw Exceptions). If you are expecting a different
|
||
type, such as a <classname>String</classname>, then provide that fully-qualified class name as shown below.
|
||
<programlisting language="xml"><![CDATA[<http:outbound-gateway id="example"
|
||
request-channel="requests"
|
||
url="http://localhost/test"
|
||
http-method="POST"
|
||
extract-request-payload="false"
|
||
expected-response-type="java.lang.String"
|
||
charset="UTF-8"
|
||
request-factory="requestFactory"
|
||
request-timeout="1234"
|
||
reply-channel="replies"/>]]></programlisting>
|
||
</para>
|
||
<para>If your outbound adapter is to be used in a unidirectional way, then you can use an outbound-channel-adapter instead. This means that
|
||
a successful response will simply execute without sending any Messages to a reply channel. In the case of any non-successful response
|
||
status code, it will throw an exception. The configuration looks very similar to the gateway:
|
||
<programlisting language="xml"><![CDATA[<http:outbound-channel-adapter id="example"
|
||
url="http://localhost/example"
|
||
http-method="GET"
|
||
channel="requests"
|
||
charset="UTF-8"
|
||
extract-payload="false"
|
||
expected-response-type="java.lang.String"
|
||
request-factory="someRequestFactory"
|
||
order="3"
|
||
auto-startup="false"/>]]></programlisting>
|
||
</para>
|
||
</section>
|
||
<section id="http-samples">
|
||
<title>HTTP Samples</title>
|
||
<section id="multipart-rest-inbound">
|
||
<title>Multipart HTTP request - RestTemplate (client) and Http Inbound Gateway (server)</title>
|
||
<para>
|
||
This example demonstrates how simple it is to send a Multipart HTTP request via Spring's RestTemplate and receive it by Spring Integration HTTP Inbound Adapter.
|
||
All we are doing is creating <classname>MultiValueMap</classname> and populating it with multi-part data. <classname>RestTemplate</classname> will take care of the rest
|
||
by converting it to <classname>MultipartHttpServletRequest</classname>
|
||
THis particular client will send a multipart Http Request which contains the name of the company as well as the image file with company logo.
|
||
<programlisting language="java"><![CDATA[RestTemplate template = new RestTemplate();
|
||
String uri = "http://localhost:8080/multipart-http/inboundAdapter.htm";
|
||
Resource s2logo =
|
||
new ClassPathResource("org/springframework/integration/samples/multipart/spring09_logo.png");
|
||
MultiValueMap map = new LinkedMultiValueMap();
|
||
map.add("company", "SpringSource");
|
||
map.add("company-logo", s2logo);
|
||
HttpHeaders headers = new HttpHeaders();
|
||
headers.setContentType(new MediaType("multipart", "form-data"));
|
||
HttpEntity request = new HttpEntity(map, headers);
|
||
ResponseEntity<?> httpResponse = template.exchange(uri, HttpMethod.POST, request, null);]]></programlisting>
|
||
</para>
|
||
<para>
|
||
That is all for the client.
|
||
</para>
|
||
<para>
|
||
On the server side we have the following configuration:
|
||
<programlisting language="xml"><![CDATA[<int-http:inbound-channel-adapter id="httpInboundAdapter"
|
||
channel="receiveChannel"
|
||
name="/inboundAdapter.htm"
|
||
supported-methods="GET, POST" />
|
||
|
||
<int:channel id="receiveChannel"/>
|
||
|
||
<int:service-activator input-channel="receiveChannel">
|
||
<bean class="org.springframework.integration.samples.multipart.MultipartReceiver"/>
|
||
</int:service-activator>
|
||
|
||
<bean id="multipartResolver"
|
||
class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>
|
||
]]></programlisting>
|
||
</para>
|
||
<para>
|
||
The 'httpInboundAdapter' will receive the request, convert it to a <classname>Message</classname> with a payload as <classname>LinkedMultiValueMap</classname> which
|
||
we are parsing in the 'multipartReceiver' service-activator;
|
||
<programlisting language="java"><![CDATA[public void receive(LinkedMultiValueMap<String, Object> multipartRequest){
|
||
System.out.println("### Successfully received multipart request ###");
|
||
for (String elementName : multipartRequest.keySet()) {
|
||
if (elementName.equals("company")){
|
||
System.out.println("\t" + elementName + " - " +
|
||
((String[]) multipartRequest.getFirst("company"))[0]);
|
||
} else if (elementName.equals("company-logo")){
|
||
System.out.println("\t" + elementName + " - as UploadedMultipartFile: " +
|
||
((UploadedMultipartFile) multipartRequest.getFirst("company-logo")).getOriginalFilename());
|
||
}
|
||
}
|
||
}
|
||
|
||
]]></programlisting>
|
||
You should see the following output:
|
||
<programlisting language="xml"><![CDATA[### Successfully received multipart request ###
|
||
company - SpringSource
|
||
company-logo - as UploadedMultipartFile: spring09_logo.png]]></programlisting>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
</chapter>
|