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

Moved the location of the documentation up a level

Browse Source
This commit is contained in:
Ben Hale
2008-02-28 17:15:39 +00:00
parent a5abac62d5
commit e79ed2cc58
14 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
spring-integration-reference/src/adapters.xml Normal file
View File

@@ -0,0 +1,150 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="adapters">
<title>Channel 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 2 release, Spring Integration includes source and target adapters
for JMS, Files, Streams, and Spring ApplicationEvents as well as a target adapter for sending e-mail.
</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><![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><![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-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>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>String generateFileName(Message message)</programlisting>
</para>
<para>
As with the JMS adapters, the most convenient way to configure File adapters is with the namespace support. 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>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><![CDATA[public interface MailHeaderGenerator {
void populateMailMessageHeader(MailMessage mailMessage, Message<?> message);
}]]></programlisting>
A static implementation is available out-of-the-box, but typically most of the properties would need to be
dynamically generated based on the message itself. The following is an example of a configured
mail adapter.
<programlisting><![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-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. Both
require an <classname>InputStream</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 defines a constructor that requires an
<classname>OutputStream</classname>, 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>