INT-1033: add more docs for jdbc

spring-integration-jdbc/src/main/resources/org/springframework/integration/jdbc/config/spring-integration-jdbc-2.0.xsd

@@ -149,7 +149,7 @@
 									polled. In general the query can return multiple
 									rows, because
 									the result will be a List (of type determined by the row
-									mapper).
+									mapper).  The query can also be specified as a nested element.
 					</xsd:documentation>
 							</xsd:appinfo>
 						</xsd:annotation>
@@ -184,7 +184,7 @@
 									An update query to execute when a message is
 									polled. If the poll is in a transaction then the
 									update will
-									roll back if the transaction does.
+									roll back if the transaction does.  The update can also be specified as a nested element.
 					</xsd:documentation>
 							</xsd:appinfo>
 						</xsd:annotation>
@@ -243,7 +243,7 @@
 										referenced in named parameters, e.g. "INSERT into FOOS (ID,
 										NAME) values (:headers[business.key],
 										:payload)". More complex
-										requirements can be implemented by 
+										requirements can be implemented by specifying a sql-parameter-source-factory.
 									</xsd:documentation>
 								</xsd:appinfo>
 							</xsd:annotation>
@@ -259,8 +259,7 @@
 									message can be
 									referenced in named parameters, e.g. "INSERT into FOOS (ID,
 									NAME) values (:headers[business.key],
-									:payload)". More complex
-									requirements can be implemented by 
+									:payload)".  The query can also be specified as a nested element.
 						</xsd:documentation>
 							</xsd:appinfo>
 						</xsd:annotation>

src/docbkx/jdbc.xml

@@ -66,15 +66,17 @@
   </poller>
 </jdbc:inbound-channel-adapter>]]></programlisting>
 
-      <para>In this example the database is polled every 1000 milliseconds,
-      and the update and select queries are both executed in the same
-      transaction. The transaction manager configuration is not shown, but as
-      long as it is aware of the data source then the poll is transactional. A
-      common use case is for the downstream channels to be direct channels
-      (the default), so that the endpoints are invoked in the same thread, and
-      hence the same transaction. then if any of them fails, the transaction
-      rolls back and the input data are reverted to their original
-      state.</para>
+      <para><note>
+           If a poller is not explicitly specified a default value will be used (and as per normal with Spring Integration can be defined as a top level bean) 
+        </note> In this example the database is polled every 1000
+      milliseconds, and the update and select queries are both executed in the
+      same transaction. The transaction manager configuration is not shown,
+      but as long as it is aware of the data source then the poll is
+      transactional. A common use case is for the downstream channels to be
+      direct channels (the default), so that the endpoints are invoked in the
+      same thread, and hence the same transaction. then if any of them fails,
+      the transaction rolls back and the input data are reverted to their
+      original state.</para>
     </section>
   </section>
 
@@ -98,16 +100,78 @@
 
         <classname>SqlParameterSourceFactory</classname>
 
-        . 
+         . 
       </note></para>
 
     <para>The outbound adapter requires a reference to either a DataSource or
     a JdbcTemplate. It can also have a
     <classname>SqlParameterSourceFactory</classname> injected to control the
-    binding of incoming message to the query. </para>
+    binding of incoming message to the query.</para>
 
     <para>If the input channel is a direct channel then the outbound adapter
     runs its query in the same thread, and therefor ethe same transaction (if
     there is one) as the sender of the message.</para>
   </section>
+
+  <section>
+    <title>Message Store</title>
+
+    <para>The JDBC module provides an implementation of the Spring Integration
+    <classname>MessageStore</classname> (important in the Claim Check pattern)
+    and <classname>MessageGroupStore</classname> (important in stateful
+    patterns like Aggregator) backed by a database. Both interfaces are
+    implemented by the JdbcMessageStore and there is also support for
+    configuring store instances in XML. For example:</para>
+
+    <programlisting><![CDATA[<jdbc:message-store id="messageStore" data-source="dataSource"/>]]></programlisting>
+
+    <para>A <classname>JdbcTemplate</classname> can be specified instead of a
+    <classname>DataSource</classname>.</para>
+
+    <para>Other optional attributes are show in the next example:</para>
+
+    <para><programlisting><![CDATA[<jdbc:message-store id="messageStore" data-source="dataSource"
+  lob-handler="lobHandler" table-prefix="MY_INT_"/>]]></programlisting>Here we
+    have specified a <classname>LobHandler</classname> for dealing with
+    messages as large objects (e.g. often necessary if using Oracle) and a
+    prefix for the table names in the queries generated by the store. The
+    table name prefix defaults to "INT_".</para>
+
+    <section>
+      <title>Initializing the Database</title>
+
+      <para>Spring Integration ships with some sample scripts that can be used
+      to initialize a database. In the spring-integration-jdbc JAR file you
+      will find scripts in the
+      <classname>org.springframework.integration.jdbc</classname> package:
+      there is a create and a drop script example for a range of common
+      database platforms. A common way to use these scripts is to reference
+      them in a <ulink
+      url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/jdbc.html#d0e24182">Spring
+      JDBC data source initializer</ulink>. Note that the scripts are provided
+      as samples or specifications of the the required table and column names.
+      You may find that you need to enhance them for production use (e.g. with
+      index declarations).</para>
+    </section>
+
+    <section>
+      <title>Partitioning a Message Store</title>
+
+      <para>It is common to use a <classname>JdbcMessageStore</classname> as a
+      global store for a group of applications, or nodes in the same
+      application. To provide some portection against name clashes, and to
+      give control over the database meta-data configuration, the message
+      store allows the tables to be partitioned in two ways. One is to use
+      separate table names, by changing the prefix as described above, and the
+      other is to specify a "region" name for partitioning data within a
+      single table. An important use case for this is using the store to
+      manage persistent queues backing a Spring Integration channel. The
+      message data for a persistent channel is keyed in the store on the
+      channel name, so if the channel names are not globally unique then there
+      is the danger of channels picking up data that was not intended for
+      them. To avoid this the message store region can be used to keep data
+      separate for different physical channels that happen to have the same
+      logical name.</para>
+    </section>
+  </section>
 </chapter>