Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added Web Services chapter

Browse Source
This commit is contained in:
Mark Fisher
2008-10-22 00:20:14 +00:00
parent 128c424f60
commit 4daddefaa4
3 changed files with 56 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
spring-integration-reference/src/adapters.xml
View File

@@ -1,123 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="adapters">
<title>Adapters</title>
<section id="adapters-intro">
<title>Introduction</title>
<para>
Spring Integration provides a number of implementations of the <interfacename>MessageSource</interfacename>
and <interfacename>MessageTarget</interfacename> interfaces that serve as adapters for interacting with
external systems or components that are not part of the messaging system. These source and target
implementations can be configured within the same <emphasis>channel-adapter</emphasis> element that we
have already discussed. Essentially, the external system or component sends-to and/or receives-from a
<interfacename>MessageChannel</interfacename>. In the 1.0 Milestone 6 release, Spring Integration includes
source and target implementations for JMS, Files, FTP, Streams, and Spring ApplicationEvents.
</para>
<para>
Adapters that allow an external system to perform request-reply operations across Spring Integration
<interfacename>MessageChannels</interfacename> are actually examples of the <emphasis>Messaging Gateway</emphasis>
pattern. Therefore, those implementations are typically called "gateways" (whereas "source" and "target"
are in-only and out-only interactions respectively). For example, Spring Integration provides a
<classname>JmsSource</classname> that is <emphasis>polled by</emphasis> the bus-managed scheduler, but
also provides a <classname>JmsGateway</classname>. The gateway differs from the source in that it is an
<emphasis>event-driven consumer</emphasis> rather than a <emphasis>polling consumer</emphasis>,
and it is capable of waiting for reply messages. Spring Integration also provides gateways for RMI and
Spring's HttpInvoker.
</para>
<para>
Finally, adapters that enable interaction with external systems by <emphasis>invoking them</emphasis> for
request/reply interactions (the response is sent back on a Message Channel) are typically called
<emphasis>handlers</emphasis> in Spring Integration, since they implement the
<interfacename>MessageHandler</interfacename> interface. Basically, these types of adapters can be
configured exactly like any POJO with the &lt;service-activator&gt; element. Spring Integration provides
RMI, HttpInvoker, and Web Service handler implementations.
</para>
<para>
All of these adapters are discussed in this section. However, namespace support is provided for many of them
and is typically the most convenient option for configuration. For examples, see
<xref linkend="namespace-adapters"/>.
</para>
</section>
<section id="adapters-email">
<title>Mail Adapters</title>
<para>
Spring Integration currently provides support for <emphasis>outbound</emphasis> email only with the
<classname>MailTarget</classname>. This adapter delegates to a configured instance of Spring's
<interfacename>JavaMailSender</interfacename>, and its various mapping strategies use Spring's
<interfacename>MailMessage</interfacename> abstraction. By default text-based mails are created when
the handled message has a String-based payload. If the message payload is a byte array, then that will
be mapped to an attachment.
</para>
<para>
The adapter also delegates to a <interfacename>MailHeaderGenerator</interfacename> for providing the
mail's properties, such as the recipients (TO, CC, and BCC), the from/reply-to, and the subject.
<programlisting language="java"><![CDATA[public interface MailHeaderGenerator {
void populateMailMessageHeader(MailMessage mailMessage, Message<?> message);
}]]></programlisting>
The default implementation will look for values in the <classname>MessageHeaders</classname> with
the following constants defining the header names:
<programlisting language="java">MailHeaders.SUBJECT
MailHeaders.TO
MailHeaders.CC
MailHeaders.BCC
MailHeaders.FROM
MailHeaders.REPLY_TO</programlisting>
</para>
<para>
A static implementation is also available out-of-the-box and may be useful for testing. However, when
customizing, the properties would typically be generated dynamically based on the message itself. The
following is an example of a configured mail adapter.
<programlisting language="xml"><![CDATA[<bean id="mailTarget"
class="org.springframework.integration.adapter.mail.MailTarget">
<property name="mailSender" ref="javaMailSender"/>
<property name="headerGenerator" ref="dynamicMailMessageHeaderGenerator"/>
</bean>]]></programlisting>
</para>
</section>
<section id="adapters-webservices">
<title>Web Service Adapters</title>
<para>
To invoke a Web Service upon sending a message to a channel, there are two options:
<classname>SimpleWebServiceHandler</classname> and
<classname>MarshallingWebServiceHandler</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 the URI of the Web Service to be
called.<programlisting language="java">simpleHandler = new SimpleWebServiceHandler(uri);
marshallingHandler = new MarshallingWebServiceHandler(uri, marshaller);
</programlisting>
Either adapter can then be referenced from a <classname>service-activator</classname> element
that is subscribed to an input-channel. The endpoint is then responsible for passing the response to the
proper reply channel. It will first check for an "output-channel" on the service-activator and will
fallback to a <emphasis>RETURN_ADDRESS</emphasis> in the original message's headers.
</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="adapters-applicationevents">
<title>ApplicationEvent Adapters</title>
<para>
Spring <classname>ApplicationEvents</classname> can also be integrated as either a source or target for Spring
Integration message channels. To receive the events and send to a channel, simply define an instance of Spring
Integration's <classname>ApplicationEventSource</classname> (as with all source implementations, this can then
be configured within a "channel-adapter" element and automatically detected by the message bus). The
<classname>ApplicationEventSource</classname> also implements Spring's <interfacename>ApplicationListener</interfacename>
interface. By default it will pass all received events as Spring Integration Messages. To limit based on the type
of event, configure the list of event types that you want to receive with the 'eventTypes' property.
</para>
<para>
To send Spring <classname>ApplicationEvents</classname>, register an instance of the
<classname>ApplicationEventTarget</classname> class as the 'target' of a Channel Adapter (such configuration will
be described in detail in <xref linkend="namespace-endpoint"/>). This target also implements Spring's
<interfacename>ApplicationEventPublisherAware</interfacename> interface and thus acts as a bridge between
Spring Integration <classname>Messages</classname> and <classname>ApplicationEvents</classname>.
</para>
</section>
</chapter>

2
spring-integration-reference/src/spring-integration-reference.xml
View File

@@ -49,9 +49,9 @@
<xi:include href="./splitter.xml"/>
<xi:include href="./aggregator.xml"/>
<xi:include href="./resequencer.xml"/>
<xi:include href="./adapters.xml"/>
<xi:include href="./file.xml"/>
<xi:include href="./jms.xml"/>
<xi:include href="./ws.xml"/>
<xi:include href="./rmi.xml"/>
<xi:include href="./httpinvoker.xml"/>
<xi:include href="./mail.xml"/>

55
spring-integration-reference/src/ws.xml Normal file
View File

@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="ws">
<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.springframework.org/spring-ws/sites/1.5/">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 the URI of the Web Service to be
called.<programlisting language="java"> simpleGateway = new SimpleWebServiceOutboundGateway(uri);
marshallingGateway = new MarshallingWebServiceOutboundGateway(uri, marshaller);
</programlisting>
</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-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[<ws:outbound-gateway id="simpleGateway"
request-channel="inputChannel"
uri="http://example.org"/>]]></programlisting>
To use Spring OXM Marshallers and/or Unmarshallers, provide bean references:
<programlisting language="xml"><![CDATA[<ws:outbound-gateway id="marshallingGateway"
request-channel="requestChannel"
uri="http://example.org"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>]]></programlisting>
<note>
Most <interfacename>Marshaller</interfacename> implementations also implement the
<interfacename>Unmarshaller</interfacename> interface. When using such a Marshaller, only the "marshaller"
attribute is necessary. Even when using a Marshaller, you may also provide a reference for the
"request-callback".
</note>
</para>
<para>
For either gateway type, the "message-factory" attribute can also be configured with a reference to any
Spring Web Services <interfacename>WebServiceMessageFactory</interfacename> implementation.
</para>
</section>
</chapter>