From f6f8949502c044b62d1b0331b7d9cd46807e3182 Mon Sep 17 00:00:00 2001
From: Mark Fisher <markfisher@vmware.com>
Date: Fri, 9 Oct 2009 14:50:18 +0000
Subject: [PATCH] INT-761 added documentation for JMS-backed Message Channels

---
 spring-integration-reference/src/jms.xml | 64 ++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/spring-integration-reference/src/jms.xml b/spring-integration-reference/src/jms.xml
index 5e51dfc361..6519b0676d 100644
--- a/spring-integration-reference/src/jms.xml
+++ b/spring-integration-reference/src/jms.xml
@@ -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>