From 79f05f67d37ce014efedbc85feef5a9f1bf509de Mon Sep 17 00:00:00 2001
From: Mark Fisher <markfisher@vmware.com>
Date: Tue, 22 Jan 2008 16:59:24 +0000
Subject: [PATCH] Added documentation for JMS adapters

---
 .../reference/src/adapters.xml                | 55 ++++++++++++++++++-
 .../reference/src/configuration.xml           | 18 ++++++
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/spring-integration-reference/reference/src/adapters.xml b/spring-integration-reference/reference/src/adapters.xml
index 6f5a688981..f2b4c32f86 100644
--- a/spring-integration-reference/reference/src/adapters.xml
+++ b/spring-integration-reference/reference/src/adapters.xml
@@ -7,9 +7,60 @@
     <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
+      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>.
+      adapters</emphasis>. In the 1.0 Milestone 1 release, Spring Integration includes adapters for JMS, Files,
+      Streams, Spring ApplicationEvents, as well as general purpose Method-invoking 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><![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>
+      In both cases, 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. In <xref linkend="namespace-adapters"/>, you will see how to configure a JMS target
+      adapter with Spring Integration's namespace support.
     </para>
   </section>
 </chapter>
\ No newline at end of file
diff --git a/spring-integration-reference/reference/src/configuration.xml b/spring-integration-reference/reference/src/configuration.xml
index 98d3032437..f1bad9bb81 100644
--- a/spring-integration-reference/reference/src/configuration.xml
+++ b/spring-integration-reference/reference/src/configuration.xml
@@ -186,6 +186,24 @@
       </para>
     </section>
 
+    <section id="namespace-adapters">
+      <title>Configuring Channel Adapters</title>
+      <para>
+        The most convenient way to configure Channel Adapters is by using the namespace support. The following examples
+        demonstrate the namespace-based configuration of source and target adapters (Spring Integration 1.0 M1 includes
+        namespace support for JMS and Files):
+        <programlisting><![CDATA[
+<jms-source connection-factory="connectionFactory" destination="inputQueue" channel="inputChannel1"/
+
+<jms-target connection-factory="connectionFactory" destination="outputQueue" channel="outputChannel1"/>
+
+<file-source directory="/tmp/input" channel="inputChannel2" poll-period="10000"/>
+
+<file-target directory="/tmp/output" channel="outputChannel2"/>
+]]></programlisting>
+      </para>
+    </section>
+
     <section id="namespace-annotationdriven">
       <title>Enabling Annotation-Driven Configuration</title>
       <para>