QPID-6108: [Java Broker Documentation] Add HA operational log messages, section related to configuration encryption and SCRAM-SHA providers.

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

4 files changed, 108 insertions, 78 deletions

diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
index 5bf1a31087..d361efb0ab 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
@@ -27,27 +27,5 @@
         Many <emphasis>Authentication Providers</emphasis> can be configured on the Broker at the same time, from which
         each <emphasis>Port</emphasis> can be assigned one.
     </para>
-    <para>
-        The following authentication providers are supported:
-        <itemizedlist>
-            <listitem><para><link linkend= "Java-Broker-Security-Anonymous-Provider">Anonymous</link>:
-            allows anonymous connections to the broker</para></listitem>
-            <listitem><para><link linkend= "Java-Broker-Security-External-Provider">External</link>:
-            delegates to external mechanisms such as SSL Client Certificate Authentication</para></listitem>
-            <listitem><para><link linkend= "Java-Broker-Security-Kerberos-Provider">Kerberos</link>:
-            uses Kerberos to authenticate connections via GSS-API.</para></listitem>
-            <listitem><para><link linkend= "Java-Broker-Security-LDAP-Provider">SimpleLDAP</link>:
-            authenticate users against an LDAP server.</para></listitem>
-            <listitem><para><link linkend= "Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link>:
-            authenticate users against credentials stored in plain text in a local file.</para></listitem>
-            <listitem><para><link linkend= "Java-Broker-Security-Base64MD5PasswordFile-Provider">Base64MD5PasswordFile</link>:
-            authenticate users against credentials stored encoded in a local file.</para></listitem>
-        </itemizedlist>
-    </para>
-    <para>
-        The Password File based providers can perform explicit management (adding, removing, changing passwords)
-        of users via the Brokers management interfaces. The other providers offer no ability to manage users as they either have no scope
-        for user management (e.g Anonymous) or delegate this task to other systems (e.g LDAP).
-    </para>
-    <para>The configuration details for Authentication Providers are covered in <xref linkend= "Java-Broker-Security-Authentication-Providers"/>.</para>
+    <para>Some Authentication Providers offer facilities for creation and deletion of users.</para>
 </section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
index 70e4047866..90193176a7 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
@@ -21,43 +21,6 @@
 -->
 <section id="Java-Broker-Concepts-Broker">
   <title>Broker</title>
-  <para>The Java Broker comprises of a number of entities. This section summaries the purpose of
-    each of the entities and describes the relationships between them. These details are developed
-    further in the sub-sections that follow.</para>
-  <para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an
-    independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists
-    in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly
-    one virtualhost.</para>
-  <para><emphasis>Ports</emphasis> accept connections for messaging and management. The Broker
-    supports any number of ports. When connecting for messaging, the user specifies a virtualhost
-    name to indicate the virtualhost to which it is to be connected.</para>
-  <para><emphasis>Authentication Providers</emphasis> assert the identity of the user as it connects
-    for messaging or management. The Broker supports any number of authentication providers. Each
-    port is associated with exactly one authentication provider. The port uses the authentication
-    provider to assert the identity of the user as new connections are received.</para>
-  <para><emphasis>Group Providers</emphasis> provide mechanisms that provide grouping of users. A
-    Broker supports zero or more group providers.</para>
-  <para><emphasis>Access Control Provider</emphasis> allows the abilities of users (or groups of
-    users) to be restrained. A Broker can have zero or one access control providers.</para>
-  <para><emphasis>Keystores</emphasis> provide a repositories of certificates and are used when the
-    Broker accepts SSL connections. Any number of keystore providers can be defined. Keystores are
-    be associated with Ports defined to accepts SSL.</para>
-  <para><emphasis>Truststores</emphasis> provide a repositories of trust and are used to validate a
-    peer. Any number of truststore provides can be defined. Truststores can be associated with Ports
-    and other entities that form SSL connections.</para>
-  <para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is
-    in use. It is the remote representation of other virtualhost nodes that form part of the same
-    group.</para>
-
-  <para>The following diagram depicts the Broker model: <figure>
-      <title>Broker Model</title>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/>
-        </imageobject>
-        <textobject>
-          <phrase>Broker Model</phrase>
-        </textobject>
-      </mediaobject>
-    </figure> These concepts will be expanded upon in the forthcoming pages. </para>
+  <para>The <emphasis>Broker</emphasis> is the outermost entity within the system.</para>
+  <para>The Broker is backed by storage. This storage is used to record the durable entities that exist beneath it.</para>
 </section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
new file mode 100644
index 0000000000..f83500e4a7
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!--
+
+ 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-Concepts-Overview">
+  <title>Overview</title>
+  <para>The Broker comprises of a number of entities. This section summaries the purpose of
+    each of the entities and describes the relationships between them. These details are developed
+    further in the sub-sections that follow.</para>
+  <para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an
+    independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists
+    in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly
+    one virtualhost.</para>
+  <para><emphasis>Ports</emphasis> accept connections for messaging and management. The Broker
+    supports any number of ports. When connecting for messaging, the user specifies a virtualhost
+    name to indicate the virtualhost to which it is to be connected.</para>
+  <para><emphasis>Authentication Providers</emphasis> assert the identity of the user as it connects
+    for messaging or management. The Broker supports any number of authentication providers. Each
+    port is associated with exactly one authentication provider. The port uses the authentication
+    provider to assert the identity of the user as new connections are received.</para>
+  <para><emphasis>Group Providers</emphasis> provide mechanisms that provide grouping of users. A
+    Broker supports zero or more group providers.</para>
+  <para><emphasis>Access Control Provider</emphasis> allows the abilities of users (or groups of
+    users) to be restrained. A Broker can have zero or one access control providers.</para>
+  <para><emphasis>Keystores</emphasis> provide a repositories of certificates and are used when the
+    Broker accepts SSL connections. Any number of keystore providers can be defined. Keystores are
+    be associated with Ports defined to accepts SSL.</para>
+  <para><emphasis>Truststores</emphasis> provide a repositories of trust and are used to validate a
+    peer. Any number of truststore provides can be defined. Truststores can be associated with Ports
+    and other entities that form SSL connections.</para>
+  <para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is
+    in use. It is the remote representation of other virtualhost nodes that form part of the same
+    group.</para>
+  <para>These concepts will be developed over the forthcoming pages. The diagrams below also help
+    put these entities in context of one and other.</para>
+  <para><figure>
+      <title>Message Flow</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/Broker-MessageFlow.png" format="PNG" scalefit="1"/>
+        </imageobject>
+        <textobject>
+          <phrase>Message Flow through the Broker</phrase>
+        </textobject>
+      </mediaobject>
+    </figure></para>
+  <para><figure>
+      <title>Broker Structure</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/>
+        </imageobject>
+        <textobject>
+          <phrase>Broker Structure</phrase>
+        </textobject>
+      </mediaobject>
+    </figure>
+  </para>
+
+</section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
index 37b54299e4..a12b58925c 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
@@ -21,19 +21,18 @@
 -->
 
 <section id="Java-Broker-Concepts-Ports">
-<title>Ports</title>
-    <para>
-        The Broker supports configuration of <emphasis>Ports</emphasis> to specify the particular AMQP messaging
-        and HTTP/JMX management connectivity it offers for use.
-    </para>
-    <para>
-        Each Port is configured with the particular <emphasis>Protocols</emphasis> and <emphasis>Transports</emphasis> it supports, as well as the <emphasis>Authentication Provider</emphasis> to be used to authenticate connections. Where SSL is in use, the <emphasis>Port</emphasis> configuration also defines which <emphasis>Keystore</emphasis> to use and (where supported) which <emphasis>TrustStore(s)</emphasis> and whether Client Certificates should be requested/required. 
-    </para>
-    <para>
-        Different <emphasis>Ports</emphasis> can support different protocols, and many <emphasis>Ports</emphasis> can be configured on the Broker.</para>
-    <para>
-        The following AMQP protocols are currently supported by the Broker:
-        <itemizedlist>
+    <title>Ports</title>
+    <para> The Broker supports configuration of <emphasis>Ports</emphasis> to specify the particular
+        AMQP messaging and HTTP/JMX management connectivity it offers for use. </para>
+    <para> Each Port is configured with the particular <emphasis>Protocols</emphasis> and
+            <emphasis>Transports</emphasis> it supports, as well as the <emphasis>Authentication
+            Provider</emphasis> to be used to authenticate connections. Where SSL is in use, the
+            <emphasis>Port</emphasis> configuration also defines which <emphasis>Keystore</emphasis>
+        to use and (where supported) which <emphasis>TrustStore(s)</emphasis> and whether Client
+        Certificates should be requested/required. </para>
+    <para> Different <emphasis>Ports</emphasis> can support different protocols, and many
+            <emphasis>Ports</emphasis> can be configured on the Broker.</para>
+    <para> The following AMQP protocols are currently supported by the Broker: <itemizedlist>
             <listitem><para><emphasis>AMQP 0-8</emphasis></para></listitem>
             <listitem><para><emphasis>AMQP 0-9</emphasis></para></listitem>
             <listitem><para><emphasis>AMQP 0-9-1</emphasis></para></listitem>
@@ -42,7 +41,20 @@
         </itemizedlist>
     </para>
 
-    <para>
-        Addittionally, HTTP and JMX ports can be configured for use by the associated management plugins.
-    </para>
+    <para> Addittionally, HTTP and JMX ports can be configured for use by the associated management
+        plugins. </para>
+    <para>This diagram explains how Ports, <link
+            linkEnd="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link>
+        and an Access Control Provider work together to allow an application to form a connection to
+        a Virtualhost.<figure>
+            <title>Control flow during Authentication</title>
+            <mediaobject>
+                <imageobject>
+                    <imagedata fileref="images/Broker-PortAuthFlow.png" format="PNG" scalefit="1"/>
+                </imageobject>
+                <textobject>
+                    <phrase>Control flow during Authentication</phrase>
+                </textobject>
+            </mediaobject>
+        </figure></para>
 </section>