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, 36 insertions, 39 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml
index e4661d6b7e..c322045336 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml
@@ -26,11 +26,13 @@
 
   <section id="Java-Broker-Ports-Configuring">
     <title>Configuring Broker Ports</title>
-    <para>The Broker Ports can be configured using
-    <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link>
-    and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para>
+    <para>
+        The Broker Ports can be configured using the
+        <link linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Introduction">HTTP management interfaces</link>.
+    </para>
 
-    <para>The following Port managing operations are available from Web Management Console:
+    <para>The following Port managing operations are available from the
+            <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>:
         <itemizedlist>
             <listitem><para>A new Port can be created by clicking "Add Port" button on the Broker tab.</para></listitem>
             <listitem><para>An existing Port details are displayed on the Port tab after clicking
@@ -44,50 +46,45 @@
     <para>Three different types of ports can be created:
         <itemizedlist>
             <listitem><para>AMQP ports accepting connections for supported AMQP protocols.</para></listitem>
-            <listitem><para>HTTP ports accepting connections for HTTP and HTTPS protocols and used by web management plugin.</para></listitem>
-            <listitem><para>RMI ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem>
+            <listitem><para>HTTP ports accepting connections for HTTP and HTTPS (by selecting the SSL transport) and used by web management plugin.</para></listitem>
+            <listitem><para>JMX related ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem>
         </itemizedlist>
     </para>
 
-    <para>On creation or editing of AMQP port the port protocols can be specified from the list of supported AMQP protocols.
-     Any number of AMQP ports with any combination of supported protocols can be configured on the Broker.</para>
-
-     <para>It is possible to create any number of HTTP/HTTPS ports. However, only two JMX ports are recommended
-     to configure on the Broker: one with RMI protocol and another with JMX_RMI protocol.
-     The creation of more JMX protocols might result in unexpected behavior. When more then two JMX ports are configured
-     the JMX plugin will pick up only two of them (having different RMI protocols) in indeterministic order.</para>
-
-    <para>Both TCP and SSL transports are supported by AMQP and HTTP ports.
-    The Keystore is required to configure on Port for SSL transport support.
-    The details of Keystore configuration are covered in <xref linkend="Java-Broker-SSL-Keystore"/>.
-    SSL transport is also supported by the JMX connector port (having protocol set to "JMX_RMI")
-    but JMX RMI port (having protocol set to "RMI") does not support SSL transport.</para>
-
-    <para>Client Certificate Authentication can be configured with AMQP ports only. This requires configuring
-    of one or more Trustores on the Port and setting of needClientAuthentication and wantClientAuthentication attributes.
-    They allow control of whether the client must present an SSL certificate. Only one of these elements is needed but both
-    may be used at the same time. A socket's client authentication setting is one of three states:
-    required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default).
-    If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication
-    it may be desirable to use the External Authentication Provider, for details see <xref linkend="Java-Broker-Security-External-Provider"/>.
-    The details how to configure Trustores are covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para>
-
-    <para>An Authentication Provider is required to configure on AMQP, HTTP and JMX connector(having protocol set to "JMX_RMI") ports.
-    JMX RMI port (having protocol set to "RMI") does not require setting of Authentication Provider.
-    For Authentication Provider configuration details see <xref linkend="Java-Broker-Security-Authentication-Providers"/></para>
+    <para>
+        It is possible to create any number of HTTP and AMQP (supporting any mixture of AMQP versions) ports, however only
+        two JMX-related ports can recommended to configure on the Broker: one with the RMI protocol for the RMI Registry to
+        advertise the JMX Connector Server and another with the JMX_RMI protocol for the JMX Connector Server itself.
+    </para>
 
-    <important>
-    Neither Port type no name can be changed for existing Port as editing of name and type is unsupported at the moment.
-    </important>
+    <para>
+        A configured <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link> must be
+        selected on ports using the AMQP, HTTP and JMX_RMI protocols.
+    </para>
+
+    <para>
+        SSL can be enabled forPorts with protocols that support it by selecting the 'SSL' transport, at which
+        point a configured <link linkend="Java-Broker-SSL-Keystore">KeyStore</link> must also be selected for the Port.
+    </para>
+
+    <para>
+        Client Certificate Authentication can be configured for AMQP ports. This requires selecting one or more configured
+        <link linkend="SSL-Truststore-ClientCertificate">TrustStores</link> on the Port and setting the <emphasis>needClientAuthentication</emphasis>
+        and <emphasis>wantClientAuthentication</emphasis> attributes as desired.
+        They allow control of whether the client must present an SSL certificate, allowing for three possible states:
+        required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default).
+        If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication
+        it may be desirable to use the <link linkend="Java-Broker-Security-External-Provider">External Authentication Provider</link>.
+    </para>
 
     <important>
-    The changes of port attributes will take effect only after broker restart.
+        Changes to port attributes will take effect only after broker restart. You should restart the broker
+        immediately if you require the attribute change sto take effect.
     </important>
 
     <important>
-    On deletion of active Port all opened connections remain opened until they are closed by the clients or Broker is shutdown
-    or connection Virtual Hosts are deleted or stopped. When Port is deleted with active connections, the creation of another Port
-    having the same port number as deleted one fails.
+        Following deletion of an active Port, the port remains bound until the Broker is restarted. You should restart the broker
+        immediately if you require preventing new connections on the port or disconnecting existing clients.
     </important>
 
   </section>