257 lines
17 KiB
XML
257 lines
17 KiB
XML
<?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 <service-activator> 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-jms">
|
|
<title>JMS Adapters</title>
|
|
<para>
|
|
Spring Integration provides two adapters for accepting JMS messages (as mentioned above):
|
|
<classname>JmsSource</classname> and <classname>JmsGateway</classname>. The former uses Spring's
|
|
<classname>JmsTemplate</classname> to receive based on a polling period. The latter configures and delegates to
|
|
an instance of Spring's <classname>DefaultMessageListenerContainer</classname>.
|
|
</para>
|
|
<para>
|
|
The <classname>JmsSource</classname> requires a reference to either a single <classname>JmsTemplate</classname>
|
|
instance or both <interfacename>ConnectionFactory</interfacename> and <interfacename>Destination</interfacename>
|
|
(a 'destinationName' can be provided in place of the 'destination' reference). The <classname>JmsSource</classname>
|
|
can then be referenced from a "channel-adapter" element that connects the source to a
|
|
<interfacename>MessageChannel</interfacename> instance. The following example defines a JMS source with
|
|
a <classname>JmsTemplate</classname> as a constructor-argument.
|
|
<programlisting language="xml"><![CDATA[<bean id="jmsSource" class="org.springframework.integration.adapter.jms.JmsSource">
|
|
<constructor-arg ref="jmsTemplate"/>
|
|
</bean>]]></programlisting>
|
|
</para>
|
|
<para>
|
|
In most cases, Spring Integration's message-driven <classname>JmsGateway</classname> is more appropriate since it
|
|
delegates to a <interfacename>MessageListener</interfacename> container, supports dynamically adjusting
|
|
concurrent consumers, and can also handle replies. The <classname>JmsGateway</classname> requires references to
|
|
a <interfacename>ConnectionFactory</interfacename>, and a <interfacename>Destination</interfacename> (or
|
|
'destinationName'). The following example defines a <classname>JmsGateway</classname> that receives from the JMS
|
|
queue called "exampleQueue". Note that the 'expectReply' property has been set to 'true' (it is 'false' by
|
|
default):
|
|
<programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.adapter.jms.JmsGateway">
|
|
<property name="connectionFactory" ref="connectionFactory"/>
|
|
<property name="destinationName" value="exampleQueue"/>
|
|
<property name="expectReply" value="true"/>
|
|
</bean>]]></programlisting>
|
|
</para>
|
|
<para>
|
|
The <classname>JmsTarget</classname> implements the <interfacename>MessageTarget</interfacename> interface
|
|
and is capable of mapping Spring Integration <interfacename>Messages</interfacename> to JMS messages and then
|
|
sending to a JMS destination. It requires either a 'jmsTemplate' reference or both 'connectionFactory' and
|
|
'destination' references (again, the 'destinationName' may be provided in place of the 'destination). In
|
|
<xref linkend="namespace-adapters"/>, you will see how to configure a JMS target adapter with Spring
|
|
Integration's namespace support.
|
|
</para>
|
|
</section>
|
|
<section id="adapters-rmi">
|
|
<title>RMI Adapters</title>
|
|
<para>
|
|
The <classname>RmiGateway</classname> is built upon Spring's <classname>RmiServiceExporter</classname>.
|
|
However, since it is adapting a <interfacename>MessageChannel</interfacename>, there is no need to specify
|
|
the <emphasis>serviceInterface</emphasis>. Likewise, the <emphasis>serviceName</emphasis> is automatically
|
|
generated based on the channel name. Therefore, creating the adapter is as simple as providing a reference
|
|
to its channel: <programlisting language="java">RmiGateway rmiGateway = new RmiGateway(channel);
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
The <classname>RmiHandler</classname> encapsulates the creation of a proxy that is capable of
|
|
communicating with an <classname>RmiGateway</classname> running in another process. Since the interface
|
|
is already known, the only required information is the URL. The URL should include the host, port (default is
|
|
'1099'), and 'serviceName'. The 'serviceName' must match that created by the
|
|
<classname>RmiGateway</classname> (the prefix is available as a constant).
|
|
<programlisting language="java">String url = "http://somehost:1099/" + RmiGateway.SERVICE_NAME_PREFIX + "someChannel";
|
|
RmiHandler rmiHandler = new RmiHandler(url);
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
<section id="adapters-httpinvoker">
|
|
<title>HttpInvoker Adapters</title>
|
|
<para>
|
|
The adapters for HttpInvoker are very similar to the RMI adapters. For a source, only the
|
|
channel needs to be provided, and for a target, only the URL. If running in a Spring MVC environment, then
|
|
the <classname>HttpInvokerGateway</classname> simply needs to be defined and provided in a
|
|
<interfacename>HandlerMapping</interfacename>. For example, the following would be exposed at the path
|
|
"http://somehost/path-mapped-to-dispatcher-servlet/httpInvokerAdapter" when a simple
|
|
<classname>BeanNameUrlHandlerMapping</classname> strategy is enabled:
|
|
<programlisting language="xml"><![CDATA[<bean name="/httpInvokerAdapter"
|
|
class="org.springframework.integration.adapter.httpinvoker.HttpInvokerGateway">
|
|
<constructor-arg ref="someChannel"/>
|
|
</bean>]]></programlisting>
|
|
When not running in a Spring MVC application, simply define a servlet in 'web.xml' whose type is
|
|
<classname>HttpRequestHandlerServlet</classname> and whose name matches the bean name of the gateway
|
|
adapter. As with the <classname>RmiHandler</classname>, the
|
|
<classname>HttpInvokerHandler</classname> only requires the URL that matches an instance of
|
|
<classname>HttpInvokerGateway</classname> running in a web application.
|
|
</para>
|
|
</section>
|
|
<section id="adapters-file">
|
|
<title>File Adapters</title>
|
|
<para>
|
|
The <classname>FileSource</classname> requires the directory as a constructor argument:
|
|
<programlisting language="java">public FileSource(File directory)</programlisting>
|
|
It can then be connected to a <interfacename>MessageChannel</interfacename> when referenced from
|
|
a "channel-adapter" element.
|
|
</para>
|
|
<para>
|
|
The <classname>FileTarget</classname> constructor also requires the 'directory' argument. The target
|
|
adapter also accepts an implementation of the <interfacename>FileNameGenerator</interfacename> strategy that
|
|
defines the following method: <programlisting language="java">String generateFileName(Message message)</programlisting>
|
|
</para>
|
|
</section>
|
|
<section id="adapters-ftp">
|
|
<title>FTP Adapters</title>
|
|
<para>
|
|
To poll a directory with FTP, configure an instance of <classname>FtpSource</classname> and then connect
|
|
it to a channel by configuring a <classname>channel-adapter</classname>. The <classname>FtpSource</classname>
|
|
expects a number of properties for connecting to the FTP server as shown below.
|
|
<programlisting language="xml"><![CDATA[<bean id="ftpSource"
|
|
class="org.springframework.integration.adapter.ftp.FtpSource">
|
|
<property name="host" value="example.org"/>
|
|
<property name="username" value="someuser"/>
|
|
<property name="password" value="somepassword"/>
|
|
<property name="localWorkingDirectory" value="/some/path"/>
|
|
<property name="remoteWorkingDirectory" value="/some/path"/>
|
|
</bean>]]></programlisting>
|
|
</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-stream">
|
|
<title>Stream Adapters</title>
|
|
<para>
|
|
Spring Integration also provides adapters for streams. Both <classname>ByteStreamSource</classname> and
|
|
<classname>CharacterStreamSource</classname> implement the <interfacename>PollableSource</interfacename>
|
|
interface. By configuring one of these within a channel-adapter element, the polling period can be configured,
|
|
and the Message Bus can automatically detect and schedule them. The byte stream version requires an
|
|
<classname>InputStream</classname>, and the character stream version requires a <classname>Reader</classname> as
|
|
the single constructor argument. The <classname>ByteStreamSource</classname> also accepts the 'bytesPerMessage'
|
|
property to determine how many bytes it will attempt to read into each <interfacename>Message</interfacename>.
|
|
</para>
|
|
<para>
|
|
For target streams, there are also two implementations: <classname>ByteStreamTarget</classname> and
|
|
<classname>CharacterStreamTarget</classname>. Each requires a single constructor argument -
|
|
<classname>OutputStream</classname> for byte streams or <classname>Writer</classname> for character streams,
|
|
and each provides a second constructor that adds the optional 'bufferSize' property. Since both of these
|
|
ultimately implement the <interfacename>MessageTarget</interfacename> interface, they can be referenced from a
|
|
<emphasis>channel-adapter</emphasis> configuration as will be described in more detail in
|
|
<xref linkend="namespace-endpoint"/>.
|
|
</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> |