249 lines
16 KiB
XML
249 lines
16 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>
|
|
Channel Adapters are the components responsible for interacting with external systems or other components that
|
|
are external to the messaging system. As the name implies, the interaction consists of adapting the external
|
|
system or component to send-to and/or receive-from a <interfacename>MessageChannel</interfacename>. Within
|
|
Spring Integration, there is a distinction between <emphasis>source adapters</emphasis> and <emphasis>target
|
|
adapters</emphasis>. In the 1.0 Milestone 3 release, Spring Integration includes source and target adapters
|
|
for JMS, RMI, Files, Streams, Spring's HttpInvoker and Spring ApplicationEvents. A source adapter for FTP is
|
|
also available as well as target adapters for sending e-mail and invoking Web Services.
|
|
</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:
|
|
<classname>JmsPollingSourceAdapter</classname> and <classname>JmsMessageDrivenSourceAdapter</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>JmsPollingSourceAdapter</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>JmsPollingSourceAdapter</classname> also requires a 'channel' property that should be
|
|
a reference to a <interfacename>MessageChannel</interfacename> instance. The adapter accepts additional
|
|
properties such as: period, initialDelay, maxMessagesPerTask, and sendTimeout. The following example defines a
|
|
JMS source adapter that polls every 5 seconds and then sends to the "exampleChannel":
|
|
<programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.adapter.jms.JmsPollingSourceAdapter">
|
|
<constructor-arg ref="jmsTemplate"/>
|
|
<property name="channel" ref="exampleChannel"/>
|
|
<property name="period" value="5000"/>
|
|
</bean>]]></programlisting>
|
|
</para>
|
|
<para>
|
|
In most cases, Spring Integration's message-driven JMS adapter is more appropriate since it delegates to a
|
|
<interfacename>MessageListener</interfacename> container and supports dynamically adjusting concurrent
|
|
consumers. The <classname>JmsMessageDrivenSourceAdapter</classname> requires references to a
|
|
<interfacename>MessageChannel</interfacename>, a <interfacename>ConnectionFactory</interfacename>, and a
|
|
<interfacename>Destination</interfacename> (or 'destinationName'). The following example defines a JMS
|
|
message-driven source adapter that receives from the JMS queue called "exampleQueue" and then sends to
|
|
the Spring Integration channel named "exampleChannel":
|
|
<programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.adapter.jms.JmsMessageDrivenSourceAdapter">
|
|
<property name="connectionFactory" ref="connectionFactory"/>
|
|
<property name="destinationName" value="exampleQueue"/>
|
|
<property name="channel" ref="exampleChannel"/>
|
|
</bean>]]></programlisting>
|
|
</para>
|
|
<para>
|
|
For both source adapter types, Spring's <interfacename>MessageConverter</interfacename> strategy is used to
|
|
convert the JMS message into a plain Java object, and then Spring Integration's
|
|
<interfacename>MessageMapper</interfacename> strategy is used to convert from the plain object to a
|
|
<interfacename>Message</interfacename>.
|
|
</para>
|
|
<para>
|
|
The <classname>JmsTargetAdapter</classname> is a <interfacename>MessageHandler</interfacename> implementation
|
|
that 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>RmiSourceAdapter</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">RmiSourceAdapter rmiSourceAdapter = new RmiSourceAdapter(channel);
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
The <classname>RmiTargetAdapter</classname> encapsulates the creation of a proxy that is capable of
|
|
communicating with an <classname>RmiSourceAdapter</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>RmiSourceAdapter</classname> (the prefix is available as a constant).
|
|
<programlisting language="java">String url = "http://somehost:1099/" + RmiSourceAdapter.SERVICE_NAME_PREFIX + "someChannel";
|
|
RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url);
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
<section id="adapters-httpinvoker">
|
|
<title>HttpInvoker Adapters</title>
|
|
<para>
|
|
The source and target 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>HttpInvokerSourceAdapter</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.HttpInvokerSourceAdapter">
|
|
<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 source
|
|
adapter. As with the <classname>RmiTargetAdapter</classname>, the
|
|
<classname>HttpInvokerTargetAdapter</classname> only requires the URL that matches an instance of
|
|
<classname>HttpInvokerSourceAdapter</classname> running in a web application.
|
|
</para>
|
|
</section>
|
|
<section id="adapters-file">
|
|
<title>File Adapters</title>
|
|
<para>
|
|
The <classname>FileSourceAdapter</classname> extends the generic <classname>PollingSourceAdapter</classname>
|
|
(just as the polling JMS adapter does). It requires the following constructor arguments:
|
|
<programlisting language="java">public FileSourceAdapter(File directory, MessageChannel channel, int period)</programlisting>
|
|
Optional properties include 'initialDelay' and 'maxMessagesPerTask'.
|
|
</para>
|
|
<para>
|
|
The <classname>FileTargetAdapter</classname> constructor only 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>FtpSourceAdapter</classname>. The adapter
|
|
expects a number of properties for connecting to the FTP server (as shown below) as well as the
|
|
'channel' and the 'period' for polling. For example, the following adapter would poll every 30 seconds:
|
|
<programlisting language="xml"><![CDATA[<bean id="ftpSource"
|
|
class="org.springframework.integration.adapter.ftp.FtpSourceAdapter">
|
|
<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"/>
|
|
<property name="channel" ref="someChannel"/>
|
|
<property name="period" value="30000"/>
|
|
</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>MailTargetAdapter</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 attributes in the <classname>MessageHeader</classname> with
|
|
the following constants defining the keys:
|
|
<programlisting language="java">MailAttributeKeys.SUBJECT
|
|
MailAttributeKeys.TO
|
|
MailAttributeKeys.CC
|
|
MailAttributeKeys.BCC
|
|
MailAttributeKeys.FROM
|
|
MailAttributeKeys.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="mailTargetAdapter"
|
|
class="org.springframework.integration.adapter.mail.MailTargetAdapter">
|
|
<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>SimpleWebServiceTargetAdapter</classname> and
|
|
<classname>MarshallingWebServiceTargetAdapter</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">simpleAdapter = new SimpleWebServiceTargetAdapter(uri);
|
|
|
|
marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller);
|
|
</programlisting>
|
|
As with the other target adapters, this can then be referenced from a <classname>MessageEndpoint</classname>
|
|
that is subscribed to a channel. The endpoint is then responsible for passing the response to the proper
|
|
channel. It will first check for a <emphasis>returnAddress</emphasis> on the original message's header, and it
|
|
will fallback to the endpoint's own default output channel.
|
|
</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>ByteStreamSourceAdapter</classname> and
|
|
<classname>CharacterStreamSourceAdapter</classname> extend the <classname>PolllingSourceAdapter</classname> so
|
|
that 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>ByteStreamSourceAdapter</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>ByteStreamTargetAdapter</classname> and
|
|
<classname>CharacterStreamTargetAdapter</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>MessageHandler</interfacename> interface, they can be referenced from an
|
|
endpoint 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>ApplicationEventSourceAdapter</classname> (as with all source adapters, if a
|
|
<classname>MessageBus</classname> is defined, it will automatically detect the event source adapter). The
|
|
<classname>ApplicationEventSourceAdapter</classname> 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>ApplicationEventTargetAdapter</classname> class as the handler of an endpoint (such configuration
|
|
will be described in detail in <xref linkend="namespace-endpoint"/>). This adapter 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> |