spring-integration/src/reference/docbook/ws.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ws"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Web Services Support</title>

  <section id="webservices-outbound">
    <title>Outbound Web Service Gateways</title>
    <para>
      To invoke a Web Service upon sending a message to a channel, there are two options - both of which build
      upon the <ulink url="http://static.springsource.org/spring-ws/site/">Spring Web Services</ulink>
      project: <classname>SimpleWebServiceOutboundGateway</classname> and
      <classname>MarshallingWebServiceOutboundGateway</classname>. The former will accept either a
      <classname>String</classname> or <interfacename>javax.xml.transform.Source</interfacename> as the message
      payload. The latter provides support for any implementation of the <interfacename>Marshaller</interfacename>
      and <interfacename>Unmarshaller</interfacename> interfaces. Both require a Spring Web Services
      <interfacename>DestinationProvider</interfacename> for determining the URI of the Web Service to be
      called.<programlisting language="java"> simpleGateway = new SimpleWebServiceOutboundGateway(destinationProvider);

 marshallingGateway = new MarshallingWebServiceOutboundGateway(destinationProvider, marshaller);
</programlisting>
      <note>
      When using the namespace support described below, you will only need to set a URI. Internally, the parser
      will configure a fixed URI DestinationProvider implementation. If you do need dynamic resolution of the
      URI at runtime, however, then the DestinationProvider can provide such behavior as looking up the URI from
      a registry. See the Spring Web Services
      <ulink url="http://static.springsource.org/spring-ws/site/apidocs/org/springframework/ws/client/support/destination/DestinationProvider.html">DestinationProvider</ulink>
      JavaDoc for more information about this strategy.
    </note>
    </para>
    <para>
      For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering
      <ulink url="http://static.springframework.org/spring-ws/site/reference/html/client.html">client access</ulink>
      as well as the chapter covering
      <ulink url="http://static.springframework.org/spring-ws/site/reference/html/oxm.html">Object/XML mapping</ulink>.
    </para>
  </section>

 <section id="webservices-inbound">
    <title>Inbound Web Service Gateways</title>
    <para>
      To send a message to a channel upon receiving a Web Service invocation, there are two options again: <classname>SimpleWebServiceInboundGateway</classname> and
      <classname>MarshallingWebServiceInboundGateway</classname>. The former will extract a <interfacename>javax.xml.transform.Source</interfacename>
      from the <classname>WebServiceMessage</classname> and set it as the message
      payload. The latter provides support for implementation of the <interfacename>Marshaller</interfacename>
      and <interfacename>Unmarshaller</interfacename> interfaces.
      If the incoming web service message is a SOAP message the SOAP Action header will be added to the headers of the
      <classname>Message</classname> that is forwarded onto the request channel.

      <programlisting language="java"> simpleGateway = new SimpleWebServiceInboundGateway();
 simpleGateway.setRequestChannel(forwardOntoThisChannel);
 simpleGateway.setReplyChannel(listenForResponseHere); //Optional

 marshallingGateway = new MarshallingWebServiceInboundGateway(marshaller);
 //set request and optionally reply channel
</programlisting>
Both gateways implement the Spring Web Services <interfacename>MessageEndpoint</interfacename>
interface, so they can be configured with a <classname>MessageDispatcherServlet</classname>
as per standard Spring Web Services configuration.
    </para>
    <para>
      For more detail on how to use these components, see the Spring Web Services reference guide's chapter covering
      <ulink url="http://static.springframework.org/spring-ws/site/reference/html/server.html">creating a Web Service</ulink>.
      The chapter covering
      <ulink url="http://static.springframework.org/spring-ws/site/reference/html/oxm.html">Object/XML mapping</ulink> is also applicable again.
    </para>
  </section>
  <section id="webservices-namespace">
    <title>Web Service Namespace Support</title>
    <para>
      To configure an outbound Web Service Gateway, use the "outbound-gateway" element from the "ws" namespace:
      <programlisting language="xml"><![CDATA[<int-ws:outbound-gateway id="simpleGateway"
                     request-channel="inputChannel"
                     uri="http://example.org"/>]]></programlisting>
      <note>
      Notice that this example does not provide a 'reply-channel'. If the Web Service were to
      return a non-empty response, the Message containing that response would be sent to the
    reply channel provided in the request Message's REPLY_CHANNEL header, and if that were
    not available a channel resolution Exception would be thrown. If you want to send the
    reply to another channel instead, then provide a 'reply-channel' attribute on the
    'outbound-gateway' element.
    </note>
    <tip>
    When invoking a Web Service that returns an empty response after using a String payload
    for the request Message, <emphasis>no reply Message will be sent by default</emphasis>.
    Therefore you don't need to set a 'reply-channel' or have a REPLY_CHANNEL header in the
    request Message. If for any reason you actually <emphasis>do</emphasis> want to receive
    the empty response as a Message, then provide the 'ignore-empty-responses' attribute with
    a value of <emphasis>false</emphasis> (this only applies for Strings, because using a
    Source or Document object simply leads to a NULL response and will therefore
    <emphasis>never</emphasis> generate a reply Message).
    </tip>

      To set up an inbound Web Service Gateway, use the "inbound-gateway":
      <programlisting language="xml"><![CDATA[<int-ws:inbound-gateway id="simpleGateway"
                    request-channel="inputChannel"/>]]></programlisting>

      To use Spring OXM Marshallers and/or Unmarshallers, provide bean references. For outbound:
      <programlisting language="xml"><![CDATA[<int-ws:outbound-gateway id="marshallingGateway"
                     request-channel="requestChannel"
                     uri="http://example.org"
                     marshaller="someMarshaller"
                     unmarshaller="someUnmarshaller"/>]]></programlisting>
      And for inbound:
      <programlisting language="xml"><![CDATA[<int-ws:inbound-gateway id="marshallingGateway"
                    request-channel="requestChannel"
                    marshaller="someMarshaller"
                    unmarshaller="someUnmarshaller"/>]]></programlisting>

      <note>
        Most <interfacename>Marshaller</interfacename> implementations also implement the
        <interfacename>Unmarshaller</interfacename> interface. When using such a
    <interfacename>Marshaller</interfacename>, only the "marshaller"
        attribute is necessary. Even when using a <interfacename>Marshaller</interfacename>,
        you may also provide a reference for the "request-callback" on the outbound gateways.
      </note>
    </para>
  <para>
    For either outbound gateway type, a "destination-provider" attribute can be specified instead of the "uri"
    (exactly one of them is required). You can then reference any Spring Web Services DestinationProvider
    implementation (e.g. to lookup the URI at runtime from a registry).
  </para>
    <para>
      For either outbound gateway type, the "message-factory" attribute can also be configured with a reference to any
      Spring Web Services <interfacename>WebServiceMessageFactory</interfacename> implementation.
    </para>
    <para>
      For the simple inbound gateway type, the "extract-payload" attribute can be set to false to forward
      the entire <interfacename>WebServiceMessage</interfacename> instead of just its payload as a
      <interfacename>Message</interfacename> to the request channel. This might be useful, for example,
      when a custom Transformer works against the <interfacename>WebServiceMessage</interfacename> directly.
    </para>
  </section>
  <section id="outbound-uri">
    <title>Outbound URI Configuration</title>
    <para>
      For all URI-schemes supported by Spring Web Services
     (<ulink url="http://static.springsource.org/spring-ws/site/reference/html/client.html#client-transports">URIs and Transports</ulink>)
     <code>&lt;uri-variable/&gt;</code> substitution is provided:
    </para>
    <programlisting language="xml"><![CDATA[<ws:outbound-gateway id="gateway" request-channel="input"
        uri="http://springsource.org/{foo}-{bar}">
    <ws:uri-variable name="foo" expression="payload.substring(1,7)"/>
    <ws:uri-variable name="bar" expression="headers.x"/>
</ws:outbound-gateway>

<ws:outbound-gateway request-channel="inputJms"
        uri="jms:{destination}?deliveryMode={deliveryMode}&amp;priority={priority}"
        message-sender="jmsMessageSender">
    <ws:uri-variable name="destination" expression="headers.jmsQueue"/>
    <ws:uri-variable name="deliveryMode" expression="headers.deliveryMode"/>
    <ws:uri-variable name="priority" expression="headers.jms_priority"/>
</ws:outbound-gateway>]]></programlisting>
    <para>
      If a <classname>DestinationProvider</classname> is supplied, variable substitution is not supported
      and a configuration error will result if variables are provided.
    </para>
	  <para>
		  <emphasis>Controlling URI Encoding</emphasis>
	  </para>
	  <para>
		  By default, the URL string is encoded (see
		  <ulink url="http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/util/UriComponentsBuilder.html">UriComponentsBuilder</ulink>)
		  to the URI object before sending the request. In some scenarios with a non-standard URI it is
		  undesirable to perform the encoding. Since <emphasis>version 4.1 </emphasis> the
		  <code>&lt;ws:outbound-gateway/&gt;</code> provides an <code>encode-uri</code> attribute.
		  To disable encoding the URL, this attribute should be set to <code>false</code> (by default it is <code>true</code>).
		  If you wish to partially encode some of the URL, this can be achieved using an <code>expression</code> within a
		  <code>&lt;uri-variable/&gt;</code>:
	  <programlisting
			  language="xml"><![CDATA[<ws:outbound-gateway url="http://somehost/%2f/fooApps?bar={param}" encode-uri="false">
          <http:uri-variable name="param"
            expression="T(org.apache.commons.httpclient.util.URIUtil)
                                             .encodeWithinQuery('Hellow World!')"/>
</ws:outbound-gateway>]]></programlisting>
		Note, <code>encode-uri</code> is ignored, if <classname>DestinationProvider</classname> is supplied.
	  </para>

  </section>
</chapter>