1 files changed, 94 insertions, 0 deletions
diff --git a/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml b/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
new file mode 100644
index 0000000000..c16d9aa227
--- /dev/null
+++ b/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<section id="Java-Broker-Stores-BDB-Store">
+  <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 the 'opt' sub-directory
+      of the brokers 'lib' directory.
+    </para>
+
+    <programlisting>Unix:
+cp je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;/lib/opt</programlisting>
+
+      <programlisting>Windows:
+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>