QPID-6108: [Java Broker Documentation] Add summary of background recovery

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

2 files changed, 45 insertions, 5 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml
index e5a87df190..33294bf7c5 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml
@@ -22,5 +22,27 @@
 
 <section id="Java-Broker-Runtime-Background-Recovery">
   <title>Background Recovery</title>
-  <para>TODO-QPID-5907</para>
+  <para>On startup of the Broker, or restart of a Virtualhost, the Broker restores all durable
+    queues and their messages from disk. In the Broker's default mode the Virtualhosts do not become
+    active until this recovery process completes. If queues have a large number of entries, this may
+    take considerable time. During this time no messaging can be performed.</para>
+  <para>The Broker has a background recovery feature allows the system to return to operation
+    sooner. If enabled the recovery process takes place in the background allow producers and
+    consumers to being work earlier.</para>
+  <para>The feature respects the message delivery order requirements of standard queues, that is any
+    messages arriving whilst the background recovery is in flight won't overtake older messages
+    still to be recovered from disk. There is an exception for the out of order queue types whilst
+    background recovery is in flight. For instance, with priority queues older lower priority
+    messages may be delivered before newer, higher priority.</para>
+  <para>To activate the feature, set a <link
+      linkend="Java-Broker-Management-Managing-Entities-General">context variable</link>
+    <literal>use_async_message_store_recovery</literal> at the desired Virtualhost, or at Broker or
+    higher to enable the feature broker-wide.</para>
+  <note>
+    <para>The background recovery feature does not write operational log messages to indicate its
+      progress. This means messages <link
+        linkend="Java-Broker-Appendix-Operation-Logging-Message-MST-1004">MST-1004</link> and <link
+        linkend="Java-Broker-Appendix-Operation-Logging-Message-MST-1005">MST-1005</link> will not
+      be seen.</para>
+  </note>
 </section>
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
index b570d87ae7..5cefd5857d 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml
@@ -58,9 +58,22 @@
       </itemizedlist>
     </para>
   </section>
+  <section id="Java-Broker-Management-Managing-Virtualhost-Context">
+    <title>Context</title>
+    <para>
+      <itemizedlist>
+        <listitem>
+          <para><emphasis>use_async_message_store_recovery</emphasis> Controls the <link
+              linkend="Java-Broker-Runtime-Background-Recovery">background recovery</link>
+            feature.</para>
+        </listitem>
+      </itemizedlist>
+    </para>
+  </section>
   <section id="Java-Broker-Management-Managing-Virtualhost-Attributes">
     <title>Attributes</title>
-    <para><itemizedlist>
+    <para>
+      <itemizedlist>
         <listitem>
           <para><emphasis>Name the virtualhost</emphasis>. This is the name the messaging clients
             refer to when forming a connection to the Broker.</para>
@@ -80,17 +93,22 @@
             transactions. See <xref linkend="Java-Broker-Runtime-Producer-Transaction-Timeout"
             /></para>
         </listitem>
-      </itemizedlist></para>
+      </itemizedlist>
+    </para>
   </section>
   <section id="Java-Broker-Management-Managing-Virtualhost-Children">
     <title>Children</title>
     <para>
       <itemizedlist>
         <listitem>
-          <para><link linkend="Java-Broker-Management-Managing-Exchanges">Exchange</link></para>
+          <para>
+            <link linkend="Java-Broker-Management-Managing-Exchanges">Exchange</link>
+          </para>
         </listitem>
         <listitem>
-          <para><link linkend="Java-Broker-Management-Managing-Queues">Queue</link></para>
+          <para>
+            <link linkend="Java-Broker-Management-Managing-Queues">Queue</link>
+          </para>
         </listitem>
         <listitem>
           <para>Connection</para>