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

INT-761 added documentation for JMS-backed Message Channels

Browse Source
This commit is contained in:
Mark Fisher
2009-10-09 14:50:18 +00:00
parent 0926a3122f
commit f6f8949502
1 changed files with 64 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
spring-integration-reference/src/jms.xml
View File

@@ -179,6 +179,70 @@
</para>
</section>
<section id="jms-channel">
<title>JMS Backed Message Channels</title>
<para>
The Channel Adapters and Gateways featured above are all intended for applications that are integrating
with other external systems. The inbound options assume that some other system is sending JMS Messages
to the JMS Destination and the outbound options assume that some other system is receiving from the
Destination. The other system may or may not be a Spring Integration application. Of course, when sending
the Spring Integration Message instance as the body of the JMS Message itself (with the 'extract-payload'
value set to false), it is assumed that the other system is based on Spring Integration. However,
that is by no means a requirement. That flexibility is one of the benefits of using a Message-based
integration option with the abstraction of "channels" or Destinations in the case of JMS.
</para>
<para>
There are cases where both the producer and consumer for a given JMS Destination are intended to be
part of the same application, running within the same process. This could be accomplished by using a
pair of inbound and outbound Channel Adapters. The problem with that approach is that two adapters are
required even though conceptually the goal is to have a single Message Channel. A better option is
supported as of Spring Integration version 2.0. Now it is possible to define a single "channel" when
using the JMS namespace.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsChannel" queue="exampleQueue"/>]]></programlisting>
</para>
<para>
The channel in the above example will behave much like a normal &lt;channel/&gt; element from the main
Spring Integration namespace. It can be referenced by both "input-channel" and "output-channel" attributes
of any endpoint. The difference is that this channel is backed by a JMS Queue instance named "exampleQueue".
This means that asynchronous messaging is possible between the producing and consuming endpoints, but
unlike the simpler asynchronous Message Channels created by adding a &lt;queue/&gt; sub-element within a
non-JMS &lt;channel/&gt; element, the Messages are not just stored in an in-memory queue. Instead those
Messages are passed within a JMS Message body, and the full power of the underlying JMS provider is then
available for that channel. Probably the most common rationale for using this alternative would be to
take advantage of the persistence made available by the <emphasis>store and forward</emphasis> approach
of JMS messaging. If configured properly, the JMS-backed Message Channel also supports transactions.
In other words, a producer would not actually write to a transactional JMS-backed channel if its send
operation is part of a transaction that rolls back. Likewise, a consumer would not physically remove a
JMS Message from the channel if the reception of that Message is part of a transaction that rolls back.
Note that the producer and consumer transactions are separate in such a scenario. This is significantly
different than the propagation of a transactional context across the simple, synchronous &lt;channel/&gt;
element that has no &lt;queue/&gt; sub-element.
</para>
<para>
Since the example above is referencing a JMS Queue instance, it will act as a point-to-point channel. If
on the other hand, publish/subscribe behavior is needed, then a separate element can be used, and a JMS
Topic can be referenced instead.
<programlisting language="xml"><![CDATA[ <jms:publish-subscribe-channel id="jmsChannel" topic="exampleTopic"/>]]></programlisting>
</para>
<para>
For either type of JMS-backed channel, the name of the destination may be provided instead of a reference.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsQueueChannel" queue-name="exampleQueueName"/>
<jms:publish-subscribe-channel id="jmsTopicChannel" topic-name="exampleTopicName"/>]]></programlisting>
</para>
<para>
In the examples above, the Destination names would be resolved by Spring's default
<classname>DynamicDestinationResolver</classname> implementation, but any implementation of the
<interfacename>DestinationResolver</interfacename> interface could be provided. Also, the JMS
<interfacename>ConnectionFactory</interfacename> is a required property of the channel, but by default
the expected bean name would be "connectionFactory". The example below provides both a custom instance
for resolution of the JMS Destination names and a different name for the ConnectionFactory.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsChannel" queue-name="exampleQueueName"
destination-resolver="customDestinationResolver"
connection-factory="customConnectionFactory"/>]]></programlisting>
</para>
</section>
<section id="jms-samples">
<title>JMS Samples</title>
<para>