QPID-4685: additional documentation updates following broker configuration model changes

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

1 files changed, 23 insertions, 35 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
index 97a6558ba3..14f9f08147 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
@@ -19,43 +19,31 @@
  under the License.
 
 -->
+<chapter id="Java-Broker-Virtual-Hosts-Configuration-File">
+  <title>Virtual Host XML configuration file</title>
 
-  <section id="Java-Broker-Virtual-Hosts-Configuration-File">
-    <title>Configuring Virtual Host using configuration file</title>
-    <para>This section describes how to configure Virtual Host using configuration XML.</para>
-    <para>Virtual Host configuration XML can hold configuration for a single Virtual Host or multiple Virtual Hosts.
-    When multiple Virtual Hosts are configured a section for the each virtual host needs to be added. It should contain a tag
-    having the same name as virtual host.
+  <section id="Java-Broker-Virtual-Hosts-Configuration-File-Introduction">
+    <title>Introduction</title>
+    <para>
+        This chapter describes how to configure Virtual Hosts using an XML file.
     </para>
-<programlisting>
-&lt;virtualhosts&gt;
-    ...
-    &lt;virtualhost&gt;                 <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"/>
-        &lt;name&gt;test&lt;/name&gt;
-        &lt;test&gt;
-          ...
-        &lt;/test&gt;
-    &lt;/virtualhost&gt;
-
-    &lt;virtualhost&gt;                 <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"/>
-        &lt;name&gt;development&lt;/name&gt;
-        &lt;development&gt;
-          ...
-        &lt;/development&gt;
-    &lt;/virtualhost&gt;
-    ...
-&lt;/virtualhosts&gt;
-        </programlisting>
-        <calloutlist>
-            <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"><para>A configuration section for a virtual host "test"</para></callout>
-            <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"><para>A configuration section for a virtual host "development"</para></callout>
-        </calloutlist>
+    <para>
+        This is no longer the preferred approach for
+        <link linkend="Java-Broker-Virtual-Hosts-Configuring-Managing">defining a VirtualHost</link> and will likely be removed
+        in a future release, however it is currently neccessary to support certain use cases such as per-virtualhost attribute
+        configuration, and specialised store configuration such as for the <link linkend="Java-Broker-Stores-HA-BDB-Store">BDB HA Message Store</link>
+    </para>
+    <para>
+        Each XML Virtual Host configuration file can hold configuration for a single Virtual Host or multiple Virtual Hosts.
+        For an example file (with multiple VirtualHosts), see <xref linkend="Java-Broker-Virtual-Host-Configuration-File-Example"/>
+    </para>
+  </section>
 
     <section id="Java-Broker-Virtual-Hosts-Configuration-File-ACL">
         <title>Configuring ACL</title>
         <para><xref linkend="Java-Broker-Security-ACLs"/> provides the details of ACL, rules, formats, etc.</para>
         <para>
-        To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml:
+        To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the virtualhosts.xml:
         </para>
 
         <programlisting>
@@ -489,7 +477,7 @@
  </section>
 
 
-  <section role="h2" id="Java-Broker-Virtual-Host-Configuration-Example">
+  <section role="h2" id="Java-Broker-Virtual-Host-Configuration-File-Example">
   <title>An example of virtual host configuration file</title>
   <example>
         <title>An example of virtual host configuration file</title>
@@ -502,7 +490,7 @@
             <store>
                 <class>org.apache.qpid.server.store.MemoryMessageStore</class>
                 <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
-                <environment-path>${QPID_WORK}/derbystore</environment-path>-->
+                <environment-path>${QPID_WORK}/derbystore/localhost</environment-path>-->
             </store>
 
             <housekeeping>
@@ -562,7 +550,7 @@
             <store>
                 <class>org.apache.qpid.server.store.MemoryMessageStore</class>
                 <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
-                <environment-path>${QPID_WORK}/derbystore</environment-path>-->
+                <environment-path>${QPID_WORK}/derbystore/development</environment-path>-->
             </store>
 
             <queues>
@@ -602,7 +590,7 @@
             <store>
                 <!--<class>org.apache.qpid.server.store.MemoryMessageStore</class>-->
                 <class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
-                <environment-path>${QPID_WORK}/derbystore</environment-path>
+                <environment-path>${QPID_WORK}/derbystore/test</environment-path>
             </store>
 
             <queues>
@@ -640,4 +628,4 @@
       </example>
   </section>
 
-</section>
\ No newline at end of file
+</chapter>