QPID-4443: add some documetnation for the memory, derby, bdb, and bdbha message stores

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1411032 13f79535-47bb-0310-9956-ffa450edef68

5 files changed, 178 insertions, 3 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
index c7a809a3bf..618533dc5f 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
@@ -294,6 +294,9 @@
     <title>Configuring a Virtual Host to be a node</title>
     <para>To configure a virtualhost as a cluster node, configure the virtualhost.xml in the following manner:</para>
     <para>
+
+    <example>
+      <title>Configuring a VirtualHost to use the BDBHAMessageStore</title>
       <programlisting language="xml"><![CDATA[
 <virtualhost>
   <name>myhost</name>
@@ -314,6 +317,7 @@
     ...
  </myvhost>
 </virtualhost>]]></programlisting>
+    </example>
     </para>
     <para>The <varname>groupName</varname> is the name of logical name of the cluster.  All nodes within the
       cluster must use the same <varname>groupName</varname> in order to be considered part of the cluster.</para>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
index 01176c21f3..9ce90f6529 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
@@ -1,4 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
 <!--
 
  Licensed to the Apache Software Foundation (ASF) under one
@@ -21,6 +25,72 @@
 -->
 
 <section id="Java-Broker-Stores-BDB-Store">
-<title>BDB Store</title>
+  <title>BDB Store</title>
+  <para>
+    The Java broker has an <emphasis>optional</emphasis> message store implementation backed by Oracle BDB JE.
+    This section will detail where to download the optional dependency from, how to add it to the broker installation,
+    and provide an example configuration for using the BDBMessageStore.
+  </para>
+
+  <section role="h3" id="Java-Broker-Stores-BDB-Store-BDBJE-Download">
+    <title>Oracle BDB JE download</title>
+    <para>
+      The BDB based message store is optional due to its dependency on Oracle BDB JE, which is distributed under the Sleepycat
+      licence. As a result of this, the dependency cant be distributed by the Apache Qpid project as part of the broker release package.
+    </para>
+    <para>
+       If you wish to use the BDBMessageStore, then you must download the Oracle BDB JE &oracleBdbProductVersion; release
+      <ulink url="&oracleJeDownloadUrl;">from the Oracle website.</ulink>
+    </para>
+    <para>
+      The download has a name in the form je-&oracleBdbProductVersion;.tar.gz. It is recommended that you
+      confirm the integrity of the download by verifying the MD5.
+    </para>
+  </section>
+
+  <section role="h3" id="Java-Broker-Stores-BDB-Store-BDBJE-Installation">
+    <title>Oracle BDB JE jar installation</title>
+    <para>
+      If you wish to use the BDBMessageStore, copy the je-&oracleBdbProductVersion;.jar from within the release
+      downloaded <link linkend="Java-Broker-Stores-BDB-Store-BDBJE-Download">above</link> into an 'opt' sub-directory
+      of the brokers 'lib' directory.
+    </para>
+
+    <programlisting>Unix:
+mkdir qpid-broker-&qpidCurrentRelease;/lib/opt
+cp je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;/lib/opt</programlisting>
+
+      <programlisting>Windows:
+mkdir qpid-broker-&qpidCurrentRelease;\lib\opt
+copy je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;\lib\opt</programlisting>
+  </section>
+
+
+
+  <section role="h3" id="Java-Broker-Stores-BDB-Store-Configuration">
+    <title>Configuration</title>
+    <para>
+      In order to use the BDBMessageStore, you must configure it for each VirtualHost desired by updating the store element
+      to specify the associated store class and provide a directory location for the data to be written, as shown below.
+    </para>
+
+    <example>
+      <title>Configuring a VirtualHost to use the BDBMessageStore</title>
+      <programlisting><![CDATA[
+<virtualhosts>
+  <virtualhost>
+    <name>vhostname</name>
+    <vhostname>
+      <store>
+        <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class>
+        <environment-path>${QPID_WORK}/bdbstore/vhostname</environment-path>
+      </store>
+      ...
+    </vhostname>
+  </virtualhost>
+</virtualhosts>
+]]></programlisting>
+    </example>
+  </section>
 
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml
index bc66821d51..042b2324de 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml
@@ -22,5 +22,35 @@
 
 <section id="Java-Broker-Stores-Derby-Store">
 <title>Derby Store</title>
+  <para>
+    The Java broker has a message store implementation backed by Apache Derby.
+    This section will detail configuration for using the DerbyMessageStore.
+  </para>
+
+  <section role="h3" id="Java-Broker-Stores-Derby-Store-Configuration">
+    <title>Configuration</title>
+    <para>
+      In order to use the DerbyMessageStore, you must configure it for each VirtualHost desired by updating the store element
+      to specify the associated store class and provide a directory location for the data to be written, as shown below.
+    </para>
+
+    <example>
+      <title>Configuring a VirtualHost to use the DerbyMessageStore</title>
+      <programlisting><![CDATA[
+<virtualhosts>
+  <virtualhost>
+    <name>vhostname</name>
+    <vhostname>
+      <store>
+        <class>org.apache.qpid.server.store.DerbyMessageStore</class>
+        <environment-path>${QPID_WORK}/derbystore/vhostname</environment-path>
+      </store>
+      ...
+    </vhostname>
+  </virtualhost>
+</virtualhosts>
+]]></programlisting>
+    </example>
+  </section>
 
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml
index 9d213598e6..e8a13c52dc 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml
@@ -21,6 +21,42 @@
 -->
 
 <section id="Java-Broker-Stores-HA-BDB-Store">
-<title>High Availability BDB Store</title>
+  <title>High Availability BDB Store</title>
+  <para>
+    The Java broker has an <emphasis>optional</emphasis> High Availability message store implementation backed by Oracle BDB JE HA.
+    This section references information on where to download the optional dependency from, how to add it to the broker
+    installation, and how to configure the BDBHAMessageStore.
+  </para>
+  <para>
+    For more detailed information about use of this store, see <xref linkend="Java-Broker-High-Availability"></xref>.
+  </para>
+
+  <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-BDBJE-Download">
+    <title>Oracle BDB JE download</title>
+    <para>
+      For details, see <xref linkend="Java-Broker-Stores-BDB-Store-BDBJE-Download"></xref>.
+    </para>
+  </section>
+
+  <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-BDBJE-Installation">
+    <title>Oracle BDB JE jar installation</title>
+    <para>
+      For details, see <xref linkend="Java-Broker-Stores-BDB-Store-BDBJE-Installation"></xref>.
+    </para>
+  </section>
+
+  <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-Configuration">
+    <title>Configuration</title>
+    <para>
+      In order to use the BDBHAMessageStore, you must configure it for each VirtualHost desired by updating the store element
+      to specify the associated store class, provide a directory location for the data to be written, and configure the
+      replication group and policies used by BDB JA HA.
+    </para>
+    <para>
+      A general configuration example is shown <link linkend="Java-Broker-High-Availability-Configuration">here</link>, however it
+      is strongly recommended you examine the wider context of <xref linkend="Java-Broker-High-Availability"></xref> for a fuller
+      discussion of the various configuration options and how to use them.
+    </para>
+  </section>
 
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml
index 32288d350a..7ca50815cd 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml
@@ -21,6 +21,41 @@
 -->
 
 <section id="Java-Broker-Stores-Memory-Store">
-<title>Memory Store</title>
+  <title>Memory Store</title>
+  <para>
+    The Java broker has an in-memory message store implementation.
+    This section will detail configuration for using the MemoryMessageStore.
+  </para>
+  <para>
+    Note: when using this store, the broker will store both persistent and non-persistent messages
+    in memory, which is to say that neither will be available following a broker restart, and the
+    ability to store new messages will be entirely constrained by the JVM heap size.
+  </para>
+
+  <section role="h3" id="Java-Broker-Stores-Derby-Store-Configuration">
+    <title>Configuration</title>
+    <para>
+      In order to use the MemoryMessageStore, you must configure it for each VirtualHost desired by updating the store element
+      to specify the associated store class, as shown below.
+    </para>
+
+    <example>
+      <title>Configuring a VirtualHost to use the MemoryMessageStore</title>
+      <programlisting><![CDATA[
+<virtualhosts>
+  <virtualhost>
+    <name>vhostname</name>
+    <vhostname>
+      <store>
+        <class>org.apache.qpid.server.store.MemoryMessageStore</class
+      </store>
+      ...
+    </vhostname>
+  </virtualhost>
+</virtualhosts>
+]]></programlisting>
+    </example>
+  </section>
+
 
 </section>