QPID-6481: Move java broker docbook into java source tree

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

1 files changed, 0 insertions, 360 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
deleted file mode 100644
index ce461d32d7..0000000000
--- a/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml
+++ /dev/null
@@ -1,360 +0,0 @@
-<?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 performed 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 database 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 initialising 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 alternative,
-            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 possible 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 value 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 configuration 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>