QPID-6108: [Java Broker Documentation] Updates for changes made during 0.30

* Remove references to virtualhost.xml
* Rework concepts section
* Rework management section to separate means of management from management of the entities themselves
* Remove references message stores
* Update JVM defect to Java 7
* ACL updates
* Add Flow to Disk

Still further changes required flagged by TODO.

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

1 files changed, 360 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml
new file mode 100644
index 0000000000..ccdce918c6
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml
@@ -0,0 +1,360 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="Java-Broker-Initial-Configuration">
+    <title>Initial Configuration</title>
+
+
+    <section id="Java-Broker-Initial-Configuration-Introduction">
+        <title>Introduction</title>
+        <para>This section describes how to perform initial configuration on the command line. Once
+            the Broker is started, subsequent management is perfomed using the <link
+                linkend="Java-Broker-Management-Channel">Management interfaces</link></para>
+        <para> The configuration for each component is stored as an entry in the broker
+            configuration store, currently implemented as a JSON file which persists changes to
+            disk, BDB or Derby databadse or an in-memory store which does not. The following
+            components configuration is stored there: <itemizedlist>
+                <listitem>
+                    <para>Broker</para>
+                </listitem>
+                <listitem>
+                    <para>Virtual Host</para>
+                </listitem>
+                <listitem>
+                    <para>Port</para>
+                </listitem>
+                <listitem>
+                    <para>Authentication Provider</para>
+                </listitem>
+                <listitem>
+                    <para>Access Control Provider</para>
+                </listitem>
+                <listitem>
+                    <para>Group Provider</para>
+                </listitem>
+                <listitem>
+                    <para>Key store</para>
+                </listitem>
+                <listitem>
+                    <para>Trust store</para>
+                </listitem>
+                <listitem>
+                    <para>Plugin</para>
+                </listitem>
+            </itemizedlist>
+        </para>
+
+        <para> Broker startup involves two configuration related items, the 'Initial Configuration'
+            and the Configuration Store. When the broker is started, if a Configuration Store does
+            not exist at the current <link linkend="Java-Broker-Initial-Configuration-Location"
+                >store location</link> then one will be initialised with the current <link
+                linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial
+                Configuration'</link>. Unless otherwise requested to <link
+                linkend="Java-Broker-Initial-Configuration-Location">overwrite the configuration
+                store</link> then subsequent broker restarts will use the existing configuration
+            store and ignore the contents of the 'Initial Configuration'. </para>
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Location">
+        <title>Configuration Store Location</title>
+        <para> The broker will default to using <link
+                linkend="Java-Broker-Initial-Configuration-Configuration-Properties"
+                >${qpid.work_dir}</link>/config.json as the path for its configuration store unless
+            otherwise instructed. </para>
+        <para> The command line argument <emphasis>-sp</emphasis> (or
+                <emphasis>--store-path</emphasis>) can optionally be used to specify a different
+            relative or absolute path to use for the broker configuration store: </para>
+        <screen>
+$ ./qpid-server -sp ./my-broker-configuration.json
+        </screen>
+
+        <para> If no configuration store exists at the specified/defaulted location when the broker
+            starts then one will be initialised using the current <link
+                linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial
+                Configuration'</link>. </para>
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Initial-Config-Location">
+        <title>'Initial Configuration' Location</title>
+        <para> The 'Initial Configuration' JSON file is used when initialiasing new broker
+            configuration stores. The broker will default to using an internal file within its jar
+            unless otherwise instructed. </para>
+        <para> The command line argument <emphasis>-icp </emphasis> (or
+                <emphasis>--initial-config-path</emphasis>) can be used to override the brokers
+            internal file and supply a <link
+                linkend="Java-Broker-Initial-Configuration-Create-Initial-Config">user-created
+                one</link>:</para>
+        <screen>
+$ ./qpid-server -icp ./my-initial-configuration.json
+        </screen>
+
+        <para> If a Configuration Store already exists at the current <link
+                linkend="Java-Broker-Initial-Configuration-Location">store location</link> then the
+            current 'Initial Configuration' will be ignored unless otherwise requested to <link
+                linkend="Java-Broker-Initial-Configuration-Location">overwrite the configuration
+                store</link>
+        </para>
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Create-Initial-Config">
+        <title>Creating an 'Initial Configuration' JSON File</title>
+
+        <para> It is possible to have the broker output its default internal 'Initial Configuration'
+            file to disk using the command line argument <emphasis>-cic</emphasis> (or
+                <emphasis>--create-initial-config</emphasis>). If the option is used without
+            providing a path, a file called <emphasis>initial-config.json</emphasis> will be created
+            in the current directory, or alternatively the file can be created at a specified
+            location: </para>
+        <screen>
+$ ./qpid-server -cic ./initial-config.json
+        </screen>
+
+        <para> The 'Initial Configuration' JSON file shares a common format with the brokers JSON
+            Configuration Store implementation, so it is possible to use a brokers Configuration
+            Store output as an initial configuration. Typically 'Initial Configuration' files would
+            not to contain IDs for the configured entities, so that IDs will be generated when the
+            configuration store is initialised and prevent use of the same IDs across multiple
+            brokers, however it may prove useful to include IDs if using the Memory <link
+                linkend="Java-Broker-Initial-Configuration-Type">Configuration Store Type</link>. </para>
+        <para> It can be useful to use <link
+                linkend="Java-Broker-Initial-Configuration-Configuration-Properties">Configuration
+                Properties</link> within 'Initial Configuration' files to allow a degree of
+            customisation with an otherwise fixed file. </para>
+        <para> For an example file, see <xref
+                linkend="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example"
+            />
+        </para>
+
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Overwrite-Config-Store">
+        <title>Overwriting An Existing Configuration Store</title>
+        <para> If a configuration store already exists at the configured <link
+                linkend="Java-Broker-Initial-Configuration-Location">store location</link> then it
+            is used and the current <link
+                linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial
+                Configuration'</link> is ignored. </para>
+        <para> The command line argument <emphasis>-os</emphasis> (or
+                <emphasis>--overwrite-store</emphasis>) can be used to force a new broker
+            configuration store to be initialised from the current 'Initial Configuration' even if
+            one exists: </para>
+        <screen>
+$ ./qpid-server -os -icp ./my-initial-configuration.json
+        </screen>
+        <para> This can be useful to effectively play configuration into one or more broker to
+            pre-configure them to a particular state, or alternatively to ensure a broker is always
+            started with a fixed configuration. In the latter case, use of the Memory <link
+                linkend="Java-Broker-Initial-Configuration-Type">Configuration Store Type</link> may
+            also be useful. </para>
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Type">
+        <title>Configuration Store Type</title>
+        <para> There are currently two implementations of the pluggable Broker Configuration Store,
+            the default one which persists content to disk in a JSON file, and another which
+            operates only in-memory and so does not retain changes across broker restarts and always
+            relies on the current <link
+                linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial
+                Configuration'</link> to provide the configuration to start the broker with. </para>
+        <para> The command line argument <emphasis>-st</emphasis> (or
+                <emphasis>--store-type</emphasis>) can be used to override the default
+                <emphasis>json</emphasis>)configuration store type and allow choosing an alterative,
+            such as <emphasis>memory</emphasis>) </para>
+        <screen>
+$ ./qpid-server -st memory
+        </screen>
+        <para> This can be useful when running tests, or always wishing to start the broker with the
+            same <link linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial
+                Configuration'</link>
+        </para>
+    </section>
+
+    <section id="Java-Broker-Initial-Configuration-Configuration-Properties">
+        <title>Customising Configuration using Configuration Properties</title>
+        <para> It is posible for 'Initial Configuration' (and Configuration Store) files to contain
+            ${properties} that can be resolved to String values at startup, allowing a degree of
+            customisation using a fixed file. Configuration Property values can be set either via
+            Java System Properties, or by specifying ConfigurationPproperties on the broker command
+            line. If both are defined, System Property values take precedence. </para>
+
+        <para> The broker has the following set of core configuration properties, with the indicated
+            default values if not otherwise configured by the user: <table>
+                <title>Base Configuration Properties</title>
+                <tgroup cols="3">
+                    <thead>
+                        <row>
+                            <entry> Name </entry>
+                            <entry> Description </entry>
+                            <entry> Value </entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry> qpid.amqp_port </entry>
+                            <entry> Port number used for the brokers default AMQP messaging port </entry>
+                            <entry> "5672" </entry>
+                        </row>
+                        <row>
+                            <entry> qpid.http_port </entry>
+                            <entry> Port number used for the brokers default HTTP management port </entry>
+                            <entry> "8080" </entry>
+                        </row>
+                        <row>
+                            <entry> qpid.rmi_port </entry>
+                            <entry> Port number used for the brokers default RMI Registry port, to
+                                advertise the JMX ConnectorServer. </entry>
+                            <entry> "8999" </entry>
+                        </row>
+                        <row>
+                            <entry> qpid.jmx_port </entry>
+                            <entry> Port number used for the brokers default JMX port </entry>
+                            <entry> "9099" </entry>
+                        </row>
+                        <row>
+                            <entry> qpid.home_dir </entry>
+                            <entry> Location of the broker installation directory, which contains
+                                the 'lib' directory and the 'etc' directory often used to store
+                                files such as group and ACL files. </entry>
+                            <entry> Defaults to the value set into the QPID_HOME system property if
+                                it is set, or remains unset otherwise unless configured by the user.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry> qpid.work_dir </entry>
+                            <entry> Location of the broker working directory, which might contain
+                                the persistent message store and broker configuration store files. </entry>
+                            <entry> Defaults to the value set into the QPID_WORK system property if
+                                it is set, or the 'work' subdirectory of the JVMs current working
+                                directory. </entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </table>
+        </para>
+
+        <para> Use of these core properties can be seen in the <link
+                linkend="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example"
+                >default 'Initial Configuration' example</link>. </para>
+
+        <para> Configuration Properties can be set on the command line using the
+                <emphasis>-prop</emphasis> (or <emphasis>--configuration-property</emphasis>)
+            command line argument: </para>
+
+        <screen>
+$ ./qpid-server -prop "qpid.amqp_port=10000" -prop "qpid.http_port=10001"
+        </screen>
+        <para> In the example above, property used to set the port number of the default AMQP port
+            is specified with the value 10000, overriding the default value of 5672, and similarly
+            the vlaue 10001 is used to override the default HTTP port number of 8080. When using the
+            'Initial Configuration' to initialise a new Configuration Store (either at first broker
+            startup, when requesting to <link linkend="Java-Broker-Initial-Configuration-Location"
+                >overwrite the configuration store</link>) these new values will be used for the
+            port numbers instead. </para>
+        <para> NOTE: When running the broker on Windows and starting it via the qpid-server.bat
+            file, the "name=value" argument MUST be quoted. </para>
+
+    </section>
+
+    <section id="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example">
+        <title>Example of JSON 'Initial Configuration'</title>
+        <para> An example of the default 'Initial Configuration' JSON file the broker uses is
+            provided below:</para>
+        <example>
+            <title>JSON 'Initial configuration' File</title>
+            <programlisting><![CDATA[
+{
+  "name": "${broker.name}",
+  "modelVersion": "2.0",
+  "defaultVirtualHost" : "default",
+  "authenticationproviders" : [ {
+    "name" : "passwordFile",
+    "type" : "PlainPasswordFile",
+    "path" : "${qpid.home_dir}${file.separator}etc${file.separator}passwd",
+    "preferencesproviders" : [{
+        "name": "fileSystemPreferences",
+        "type": "FileSystemPreferences",
+        "path" : "${qpid.work_dir}${file.separator}user.preferences.json"
+    }]
+  } ],
+  "ports" : [  {
+    "name" : "AMQP",
+    "port" : "${qpid.amqp_port}",
+    "authenticationProvider" : "passwordFile"
+  }, {
+    "name" : "HTTP",
+    "port" : "${qpid.http_port}",
+    "authenticationProvider" : "passwordFile",
+    "protocols" : [ "HTTP" ]
+  }, {
+    "name" : "RMI_REGISTRY",
+    "port" : "${qpid.rmi_port}",
+    "protocols" : [ "RMI" ]
+  }, {
+    "name" : "JMX_CONNECTOR",
+    "port" : "${qpid.jmx_port}",
+    "authenticationProvider" : "passwordFile",
+    "protocols" : [ "JMX_RMI" ]
+  }],
+  "virtualhostnodes" : [ {
+    "name" : "default",
+    "type" : "JSON",
+    "virtualHostInitialConfiguration" : "{ \"type\" : \"DERBY\" }"
+  } ],
+  "plugins" : [ {
+    "type" : "MANAGEMENT-HTTP",
+    "name" : "httpManagement"
+  }, {
+    "type" : "MANAGEMENT-JMX",
+    "name" : "jmxManagement"
+  } ]
+}
+]]></programlisting>
+            <para>In the configuration above the following entries are stored: <itemizedlist>
+                    <listitem>
+                        <para> Authentication Provider of type
+                                <emphasis>PlainPasswordFile</emphasis> with name "passwordFile".
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para> Four Port entries: "AMQP", "HTTP", "RMI_REGISTRY", "JMX_CONNECTOR".
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para> Virtualhost Node called default. On initial startup, it
+                            virtualHostInitialConfiguration will cause a virtualhost to be created
+                            with the same name. The confiuration will be stored in a
+                                <emphasis>JSON</emphasis> configuration store, the message data will
+                            be stored in a <emphasis>DERBY</emphasis> message store.</para>
+                    </listitem>
+                    <listitem>
+                        <para>Two management plugins: "jmxManagement" of type "MANAGEMENT-JMX" and
+                            "httpManagement" of type "MANAGEMENT-HTTP".</para>
+                    </listitem>
+                    <listitem>
+                        <para>Broker attributes are stored as a root entry.</para>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </example>
+    </section>
+
+</chapter>