INT-2282, INT-2284

added general Message Store section to reference manual, added GemfireMessageStore section

docs/src/reference/docbook/changes-1.0-2.0.xml

@@ -82,7 +82,7 @@
             We now provide support for the <ulink url="http://www.eaipatterns.com/MessageStore.html">Message Store</ulink> pattern.
             The Message Store provides a strategy for persisting messages on behalf of any process whose scope extends beyond a single
             transaction, such as the Aggregator and Resequencer. Many sections of this document provide samples on how to use a Message Store as it
-            affects several areas of Spring Integration. See <xref linkend="claim-check"/>,
+            affects several areas of Spring Integration. See <xref linkend="message-store"/>, <xref linkend="claim-check"/>,
             <xref linkend="channel"/>, <xref linkend="aggregator"/>, <xref linkend="jdbc"/>, and <xref linkend="resequencer"/> for more details
             </para>
         </section>

docs/src/reference/docbook/gemfire.xml

@@ -125,4 +125,44 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/gemfire
 	This adapter also supports the <code>order</code> attribute which may be useful if it is bound to a PublishSubscribeChannel.  
 	</para>
   </section>
+  
+  <section id="gemfire-message-store">
+    <title>Gemfire Message Store</title>
+	
+	<para>
+    As described in EIP, a <ulink url="http://www.eaipatterns.com/MessageStore.html">Message Store</ulink> allows you to persist Messages.
+    This can be very useful when dealing with components that have a capability to buffer messages
+    (<emphasis>QueueChannel, Aggregator, Resequencer</emphasis>, etc.) if reliability is a concern.
+    In Spring Integration, the MessageStore strategy also provides the foundation for the 
+	<ulink url="http://www.eaipatterns.com/StoreInLibrary.html">ClaimCheck</ulink> pattern, which is described in EIP as well.
+	</para>
+
+	<para>
+    Spring Integration's Gemfire module provides the <classname>GemfireMessageStore</classname> which is an implementation of both the
+    the <classname>MessageStore</classname> strategy (mainly used by the <emphasis>QueueChannel</emphasis> and <emphasis>ClaimCheck</emphasis>
+    patterns) and the <classname>MessageGroupStore</classname> strategy (mainly used by the <emphasis>Aggregator</emphasis> and
+    <emphasis>Resequencer</emphasis> patterns).
+    </para>
+
+	<para>
+	<programlisting lang="xml"><![CDATA[<bean id="gemfireMessageStore" class="org.springframework.integration.gemfire.store.GemfireMessageStore">
+		<constructor-arg ref="myCache"/>
+	</bean>
+	
+	<bean id="myCache" class="org.springframework.data.gemfire.CacheFactoryBean"/>
+
+<int:channel id="somePersistentQueueChannel">
+    <int:queue message-store="gemfireMessageStore"/>
+<int:channel>
+
+<int:aggregator input-channel="inputChannel" output-channel="outputChannel"
+         message-store="gemfireMessageStore"/>]]></programlisting>
+    </para>
+
+    <para>
+    Above is a sample <classname>GemfireMessageStore</classname> configuration that shows its usage by a <emphasis>QueueChannel</emphasis>
+    and an <emphasis>Aggregator</emphasis>. As you can see it is a simple bean configuration, and it expects a
+    <classname>GemFireCache</classname> (created by <classname>CacheFactoryBean</classname>) as a constructor argument.
+    </para>
+  </section>
 </chapter>

docs/src/reference/docbook/jdbc.xml

@@ -158,8 +158,8 @@
     binding of the incoming message to the query.</para>
   </section>
 
-  <section id="message-store">
-    <title>Message Store</title>
+  <section id="jdbc-message-store">
+    <title>JDBC Message Store</title>
 
     <para>The JDBC module provides an implementation of the Spring Integration
     <classname>MessageStore</classname> (important in the Claim Check pattern)

docs/src/reference/docbook/message-store.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="message-store"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Message Store</title>
+  <para>
+   Enterprise Integration Patterns (EIP) identifies several patterns that have capabilities to buffer messages. For example; 
+   <emphasis>Aggregator</emphasis> buffers messages until they can be released and <emphasis>QueueChannel</emphasis> buffers 
+   messages until consumers explicitly receive <emphasis>Messages</emphasis> from this <emphasis>QueueChannel</emphasis>. 
+   Because of the failures that can occur at any point within your message flow EIP components that buffer 
+   messages also introduce a point where messages could be lost.  
+  </para>
+  
+  <para>
+  To mitigate the risk of loosing Messages EIP defines <ulink url="http://eaipatterns.com/MessageStore.html">Message Store</ulink> pattern which allows 
+  EIP components to store <emphasis>Messages</emphasis> typically in some type of persistent store (e.g., RDBMS).
+  </para>
+  
+  <para>
+  Spring Integration provides support for <emphasis>Message Store</emphasis> pattern by 
+  a) defining a <classname>org.springframework.integration.store.MessageStore</classname> strategy and providing several implementations of this strategy, 
+  b) exposing <code>message-store</code> attribute on all components that have capabilities to buffer messages allowing 
+  you to inject an instance of the <classname>MessageStore</classname>.
+  </para>
+  
+  <para>Details on how to configure a specific <emphasis>Message Store</emphasis> implementation and/or how to inject 
+  <classname>MessasgeStore</classname> implementation into the specific buffering component are described 
+  throughout the manual (see specific component, such as <emphasis>QueueChannel</emphasis>, <emphasis>Aggregator</emphasis>, 
+  <emphasis>Resequencer</emphasis> etc.), but here are a couple of samples to give you an idea:
+  </para>
+  
+  <para>
+  QueueChannel
+  <programlisting language="xml"><![CDATA[<int:channel id="myQueueChannel">
+    <int:queue message-store="refToMessageStore"/> 
+<int:channel>]]></programlisting> 
+  </para>
+  
+  <para>
+  Aggregator
+  <programlisting language="xml"><![CDATA[<int:aggrefator . . . message-store="refToMessageStore"/>]]></programlisting>
+  </para>
+  
+  <para>
+  By default <emphasis>Messages</emphasis> are stored in-memory using <classname>org.springframework.integration.store.SimpleMessageStore</classname> implementation of <classname>MessageStore</classname>.
+  However we also provide implementations of MessageStore for various data-stores. Below is a complete list of supported implementations:
+  
+      <itemizedlist>
+          <listitem><xref linkend="jdbc-message-store"/> - uses RDBMS to store Messages</listitem>
+          <listitem><xref linkend="redis-message-store"/> - uses Redis key/value datastore to store Messages</listitem>
+          <listitem><xref linkend="mongodb-message-store"/> - uses MongoDB document store to store Messages</listitem>
+          <listitem><xref linkend="gemfire-message-store"/> - uses Gemfire distributed cache to store Messages</listitem>
+      </itemizedlist>
+  </para>
+
+</section>

docs/src/reference/docbook/system-management.xml

@@ -6,5 +6,7 @@
   
   <xi:include href="./jmx.xml"/>
   <xi:include href="./message-history.xml"/>
+  <xi:include href="./message-store.xml"/>
   <xi:include href="./control-bus.xml"/>
+ 
 </chapter>