You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2014/10/06 08:57:01 UTC
svn commit: r1629579 [3/4] - in /qpid/trunk/qpid/doc/book/src: java-broker/
java-broker/concepts/ java-broker/images/ java-broker/management/
java-broker/management/channels/ java-broker/management/managing/
jms-client-0-8/
Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml)
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml&r1=1629242&r2=1629579&rev=1629579&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml Mon Oct 6 06:56:59 2014
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE entities [
-<!ENTITY % entities SYSTEM "commonEntities.xml">
+<!ENTITY % entities SYSTEM "../../commonEntities.xml">
%entities;
]>
<!--
@@ -24,10 +24,10 @@
-->
-<section id="Java-Broker-Configuring-And-Managing-JMX-Management">
+<section id="Java-Broker-Management-Channel-JMX">
<title>JMX Management</title>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Introduction">
+ <section id="Java-Broker-Management-Channel-JMX-Introduction">
<title>Introduction</title>
<para>The JMX management plugin provides a series of managed beans (MBeans) allowing you to
control and monitor the Broker via an industry compliant interface. This provides a
@@ -39,15 +39,15 @@
plugin.</para>
<important>
<para>For new development work, the reader is directed towards the strategic <link
- linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management
+ linkend="Java-Broker-Management-Channel-Web-Console">Web Management
Console</link> and the <link
- linkend="Java-Broker-Configuring-And-Managing-REST-API">REST API</link>. Use the
+ linkend="Java-Broker-Management-Channel-REST-API">REST API</link>. Use the
Web/REST interfaces in preference to JMX whenever possible. The JMX interface may be
withdrawn in a future release.</para>
</important>
</section>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-DefaultConfiguration">
+ <section id="Java-Broker-Management-Channel-JMX-Plugin-DefaultConfiguration">
<title>Default Configuration</title>
<para>By default, the Broker is shipped with JMX enabled.</para>
<para>The RMI registry port runs on port <literal>8999</literal> and the JMX connector on
@@ -56,11 +56,11 @@
url="&oracleJdkDocUrl;java/lang/management/ManagementFactory.html#getPlatformMBeanServer()"
>Platform MBeanServer</ulink>.</para>
<para>To change these settings, use the <link
- linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management
+ linkend="Java-Broker-Management-Channel-Web-Console">Web Management
interface</link>.</para>
</section>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX">
+ <section id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX">
<title>Connecting to JMX</title>
<para>The following example uses Jconsole to illustrates how to connect to JMX and assume
the defaults described above. Jconsole is a management tool that comes with the JDK. It
@@ -74,14 +74,14 @@
<para>To start Jconsole on the command line, type:</para>
<programlisting><![CDATA[jconsole]]></programlisting>
<section
- id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Local">
+ id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-Local">
<title>Local</title>
<para>To connect to a Broker running locally, simply select the process from the list.
You can identify the Broker by looking for its classname
<literal>org.apache.qpid.server.Main</literal>.</para>
</section>
<section
- id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Remote">
+ id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-Remote">
<title>Remote</title>
<para>To connect to a broker running remotely, provide the hostname and port number of
the <emphasis>RMI registry port</emphasis> (e.g. <literal>hostname:8999</literal>)
@@ -99,7 +99,7 @@
<title>Qpid MBean hierarchy</title>
<graphic fileref="images/JMX-Connect-MBeans.png"/>
</figure>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-SSL">
+ <section id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-SSL">
<title>Connecting to a remote Broker protected by SSL</title>
<para>If you are connecting to a remote Broker whose JMX connector port has been secured
with SSL certificate signed by a private CA (or a self-signed certificate), you will
@@ -109,7 +109,7 @@
</section>
</section>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Example-Client">
+ <section id="Java-Broker-Management-JMX-Example-Client">
<title>Example JMX Client</title>
<para>The following java snippet illustrates a JMX client that connects to Qpid over JMX
passing a userid and password, looks up the <ulink
@@ -119,7 +119,7 @@
<para>A full introduction to custom JMX clients is beyond the scope of this book. For this
the reader is directed toward Oracle's <ulink url="&oracleJmxTutorial;">JMX
tutorial.</ulink></para>
- <example id="Java-Broker-Configuring-And-Managing-JMX-Example-Client-Code">
+ <example id="Java-Broker-Management-JMX-Example-Client-Code">
<title>JMX Client illustrating the creation of a new queue</title>
<programlisting language="java">
Map<String, Object< environment = new HashMap<String, Object>();
@@ -140,7 +140,7 @@ managedBroker.createNewQueue("myqueue",
<literal>qpid-management-common</literal> artefact.</para>
</section>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-MBeans">
+ <section id="Java-Broker-Management-Channel-JMX-MBeans">
<title>The MBeans</title>
<para>The following table summarises the available MBeans. The MBeans are self-describing:
each attribute and operation carry a description describing their purpose. This
Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml)
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml&r1=1629242&r2=1629579&rev=1629579&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml Mon Oct 6 06:56:59 2014
@@ -1,4 +1,4 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="utf-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -20,7 +20,7 @@
-->
-<chapter id="Java-Broker-Queues">
- <title>Queues</title>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues-OtherTypes.xml"/>
-</chapter>
+<section id="Java-Broker-Management-Channel-QMF">
+ <title>QMF</title>
+ <para>QMF is provided by an optional plugin.</para>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,354 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Channel-REST-API">
+ <title>REST API</title>
+ <para> This section provides a brief overview of the REST interface, which can be used directly to
+ monitor and manage the Broker instance.. </para>
+
+ <para>The REST interface support traditional REST model which uses the GET method requests to
+ retrieve the information about broker configured objects, DELETE method requests to delete the
+ configured object, PUT to create or update the configured object and POST to perform the
+ configured objects updates not available with the PUT requests.</para>
+ <para>The REST API is versioned with the version number built into the URL. The general form of
+ the the URL is <literal>/api/<version></literal>. For convience the alias
+ <literal>latest</literal> signifies the latest supported version. There are also some
+ ancillary service prefixed by <literal>/service</literal>.</para>
+
+ <para>The table below lists the available REST services with brief description how they can be
+ used.</para>
+
+ <table>
+ <title>Rest services</title>
+ <tgroup cols="6">
+ <thead>
+ <row>
+ <entry>REST Service URL</entry>
+ <entry>Description</entry>
+ <entry>GET</entry>
+ <entry>PUT</entry>
+ <entry>POST</entry>
+ <entry>DELETE</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>/api/<ver>/broker</para>
+ </entry>
+ <entry>
+ <para>Rest service to manage broker instance</para>
+ </entry>
+ <entry>
+ <para>Retrieves the details of broker configuration</para>
+ </entry>
+ <entry>
+ <para>Updates broker attributes</para>
+ </entry>
+ <entry>
+ <para>Not implemented yet</para>
+ </entry>
+ <entry>
+ <para>Not implemented yet</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/authenticationprovider</para>
+ <para>/api/<ver>/authenticationprovider/<authentication provider
+ name></para>
+ </entry>
+ <entry>Rest service to manage authentication providers on the broker</entry>
+ <entry>Retrieves the details about authentication providers</entry>
+ <entry>Creates or updates authentication providers</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes authentication providers</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/accesscontrolprovider</para>
+ </entry>
+ <entry>Rest service to manage access control providers</entry>
+ <entry>Retrieves the details about access control providers</entry>
+ <entry>Creates access control provider</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes access control provider(s)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/user</para>
+ <para>/api/<ver>/user/<authentication provider name>/<user
+ name></para>
+ </entry>
+ <entry>Rest service to manage user account</entry>
+ <entry>Retrieves the details about user account</entry>
+ <entry>Creates user account, updates user password</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes user account</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/groupprovider</para>
+ <para>/api/<ver>/groupprovider/<group provider name></para>
+ </entry>
+ <entry>Rest service to manage group providers</entry>
+ <entry>Retrieves the details about group provider(s)</entry>
+ <entry>Creates group provider</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes groups providers</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/group</para>
+ <para>/api/<ver>/group/<group provider name>/<group name></para>
+ </entry>
+ <entry>Rest service to manage user group</entry>
+ <entry>Retrieves the details about user group</entry>
+ <entry>Creates group</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes group</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/groupmember</para>
+ <para>/api/<ver>/groupmember/<group provider name >/<group
+ name>/<user name></para>
+ </entry>
+ <entry>Rest service to manage group member(s)</entry>
+ <entry>Retrieves the details about group member(s)</entry>
+ <entry>Add user to group</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes user from group</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/port</para>
+ <para>/api/<ver>/port/<port name></para>
+ </entry>
+ <entry>Rest service to manage broker ports(s)</entry>
+ <entry>Retrieves the details about the broker port(s)</entry>
+ <entry>Creates or updates port</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes ports</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/keystore</para>
+ </entry>
+ <entry>Rest service to manage KeyStores</entry>
+ <entry>Retrieves the details about KeyStore</entry>
+ <entry>Creates or updates KeyStore</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes KeyStore(s)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/truststore</para>
+ </entry>
+ <entry>Rest service to manage TrustStore</entry>
+ <entry>Retrieves the details about TrustStore</entry>
+ <entry>Creates or updates TrustStore</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes TrustStore(s)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/plugin</para>
+ </entry>
+ <entry>Rest service to manage plugins</entry>
+ <entry>Retrieves the details about plugins</entry>
+ <entry>Updates plugin attributes</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/virtualhostnode</para>
+ <para>/api/<ver>/virtualhostnode/<virtualhostnode name></para>
+ </entry>
+ <entry>Rest service to manage virtualhost node(s)</entry>
+ <entry>Retrieves the details about the virtualhost node(s)</entry>
+ <entry>Creates/Updates virtualhost node</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes virtualhost node</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/virtualhost</para>
+ <para>/api/<ver>/virtualhost/<virtualhostnode name>/<virtualhost
+ name></para>
+ </entry>
+ <entry>Rest service to manage virtualhost(s)</entry>
+ <entry>Retrieves the details about the virtualhost(s)</entry>
+ <entry>Creates/Updates virtualhost</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes virtualhost</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/queue</para>
+ <para>/api/<ver>/queue/<virtualhostnode name>/<virtualhost
+ name>/<queue name></para>
+ </entry>
+ <entry>Rest service to manage queue(s)</entry>
+ <entry>Retrieves the details about the queue(s)</entry>
+ <entry>Creates queue</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes queue</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/exchange</para>
+ <para>/api/<ver>/exchange/<virtualhostnode name>/<virtualhost
+ name>/<exchange name></para>
+ </entry>
+ <entry>Rest service to manage exchange(s)</entry>
+ <entry>Retrieves the details about the exchange(s)</entry>
+ <entry>Creates exchange</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes exchange</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/binding</para>
+ <para>/api/<ver>/binding/<virtualhostnode name>/<virtualhost
+ name>/<exchange name>/<queue name>/<binding name></para>
+ </entry>
+ <entry>Rest service to manage binding(s)</entry>
+ <entry>Retrieves the details about the binding(s)</entry>
+ <entry>Binds a queue to an exchange</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Deletes binding</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/connection</para>
+ <para>/api/<ver>/connection/<virtualhostnode name>/<virtualhost
+ name>/<connection name></para>
+ </entry>
+ <entry>Rest service to manage connection(s)</entry>
+ <entry>Retrieves the details about the connection(s)</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/api/<ver>/session</para>
+ <para>/api/<ver>/session/<virtualhostnode name>/<virtualhost
+ name>/<connection name>/<session name></para>
+ </entry>
+ <entry>Rest service to manage session(s)</entry>
+ <entry>Retrieves the details about the session(s)</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/message/<virtualhost name>/<queue name></para>
+ </entry>
+ <entry>Rest service to manage messages(s)</entry>
+ <entry>Retrieves the details about the messages(s)</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Copies, moves messages</entry>
+ <entry>Deletes messages</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/message-content/<virtualhost name>/<queue name></para>
+ </entry>
+ <entry>Rest service to retrieve message content</entry>
+ <entry>Retrieves the message content</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/logrecords</para>
+ </entry>
+ <entry>Rest service to retrieve broker logs</entry>
+ <entry>Retrieves the broker logs</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/sasl</para>
+ </entry>
+ <entry>Sasl authentication</entry>
+ <entry>Retrieves user current authentication status and broker supported SASL
+ mechanisms</entry>
+ <entry>Authenticates user using supported SASL mechanisms</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/logout</para>
+ </entry>
+ <entry>Log outs</entry>
+ <entry>Log outs user</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ <entry>Not implemented yet</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>The REST URLs are hierarchical. It is permitted to replace rest URL elements with an
+ "asterisks" in GET requests to denote all object of a particular type. Additionally, trailing
+ object type in the URL hierarchy can be omitted. In this case GET request will return all of the
+ object underneath of the current object.</para>
+ <para>For example, for binding URL
+ http://localhost:8080/api/latest/binding/<vhost node>/<vhost>/<exchange>/<queue>/<binding>
+ replacing of <emphasis><exchange></emphasis> with "asterisks"
+ (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/*/<queue>/<binding>)
+ will result in the GET response containing the list of bindings for all of the exchanges in the
+ virtualhost having the given name and given queue. If <emphasis><binding></emphasis> and
+ <emphasis><queue></emphasis> are omitted in binding REST URL
+ (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/<exchangename>) the GET
+ request will result in returning all bindings for all queues for the given exchange in the
+ virtual host. </para>
+ <example>
+ <title>Examples of queue creation using curl (authenticating as user admin):</title>
+ <programlisting><![CDATA[
+#create a durable queue
+curl --user admin -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename>
+#create a durable priority queue
+curl --user admin -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename>
+ ]]></programlisting>
+ </example>
+ <example>
+ <title>Example of binding a queue to an exchange using curl</title>
+ <programlisting><![CDATA[
+curl --user admin -X PUT -d '{}' http://localhost:8080/api/latest/binding/<vhostnode name>/<vhostname>/<exchangename>/<queue-name>/<binding-name>
+ ]]></programlisting>
+ </example>
+ <para> NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is first
+ necessary enable Basic authentication for HTTP within the HTTP Management Configuration (it is
+ off by default). For details see <xref
+ linkend="Java-Broker-Management-Managing-Plugin-HTTP"/>
+ </para>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,119 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Channel-Web-Console">
+ <title>Web Management Console</title>
+ <para> The Web Management Console provides a simple and intuitive interface for the Management
+ and Control of the Broker. From here, all aspects of the Broker can be controled, including: <itemizedlist>
+ <listitem>
+ <para>add, remove and monitor queues</para>
+ </listitem>
+ <listitem>
+ <para>inspect, move, copy or delete messages</para>
+ </listitem>
+ <listitem>
+ <para>add, remove and monitor virtualhosts</para>
+ </listitem>
+ <listitem>
+ <para>configure and control high availabiliy</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The remainder of the section provides an introduction to the web managemnet console and
+ its use.</para>
+ <section id="Java-Broker-Management-Channel-Web-Console-Accessing">
+ <title>Accessing the Console</title>
+ <para>The Web Management Console is provided by the HTTP Management Plugin. Providing the
+ HTTP Management Plugin is in its default configuration, the Web Management Console can
+ be accessed by pointing a brower at the following URL:</para>
+ <para><literal>http://myhost.mydomain.com:8080</literal></para>
+ <para>The Console will prompt you to login using a username and password.</para>
+ <example>
+ <title>Web Management Console - Authentication</title>
+ <screenshot>
+ <graphic fileref="images/Management-Web-Auth.png" width="600px"/>
+ </screenshot>
+ </example>
+ </section>
+ <section id="Java-Broker-Management-Channel-Web-Console-Orientation">
+ <title>Orientation</title>
+ <para>After you have logged on you will see a screen similar to the following. The elements
+ of the screen are now explained.</para>
+ <example>
+ <title>Web Management Orientation - Console</title>
+ <screenshot>
+ <graphic fileref="images/Management-Web-Console.png" width="600px"/>
+ </screenshot>
+ </example>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>A</emphasis> - Hierarchy view. Expandable/collapsable view showing all entities
+ within the Broker. Double click on an entity name to cause its tab to be
+ opened. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>B</emphasis> - Tab. Shows the details of an entity including its attributes and its
+ child entities. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>C</emphasis> - Occluded tab. Click tab name to bring the tab to the front.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>D</emphasis> - Auto restore check box. Checked tabs will be automatically restored on
+ subsequent login.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>E</emphasis> - Close. Click to close the tab.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>F</emphasis> - User Menu. Access to Preferences, Logout and Help.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <example>
+ <title>Web Management Orientation - Tab</title>
+ <screenshot>
+ <graphic fileref="images/Management-Web-Tab.png" width="600px"/>
+ </screenshot>
+ </example>
+ <para>The elements of a tab are now explained: <itemizedlist>
+ <listitem>
+ <para><emphasis>1</emphasis> - Attribute Panel. Shows the attributes of the entity. Click the panel
+ title bar opens/closes the panel.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>2</emphasis> - Child Panels. Panels containing a table listing the children of the entity. Click the panel
+ title bar opens/closes the panel.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>3</emphasis> - Child Row. Row summarizing a child entity. Double click to open the
+ child tab.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>4</emphasis> - Child Operations. Buttons to add a new child or perform operations on existing children.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+</section>
Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml)
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml Mon Oct 6 06:56:59 2014
@@ -20,7 +20,10 @@
-->
-<section id="Java-Broker-Configuring-And-Managing-Other-Tooling">
-<title>Other Tooling</title>
-
+<section id="Java-Broker-Management-Managing-Access-Control-Providers">
+ <title>Access Control Providers</title>
+ <para>An <link linkend="Java-Broker-Concepts-Access-Control-Providers">Access Control
+ Provider</link> governs who may do what within the Broker. It governs both messaging and
+ management.</para>
+ <para>See <xref linkend="Java-Broker-Security-ACLs"/></para>
</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,51 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Authentication-Providers">
+ <title>Authentication Providers</title>
+ <para>
+ <link linkend="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link> are used by <link linkend="Java-Broker-Concepts-Ports">Ports</link> to
+ authenticate connections. </para>
+ <para>See <xref linkend="Java-Broker-Security-Authentication-Providers"/></para>
+
+ <section id="Java-Broker-Management-Managing-Authentication-Providers-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name the authentication</emphasis>.</para>
+ </listitem>
+ </itemizedlist></para>
+ <para>Other attributes are provider specific.</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Authentication-Providers-Children">
+ <title>Children</title>
+ <para>None</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Authentication-Providers-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ <important>
+ <para>When updating an existing authentication provider, changes become effective until
+ the Broker is restarted.</para>
+ </important>
+ </section>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,83 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Broker">
+ <title>Broker</title>
+ <para>The <link linkend="Java-Broker-Concepts-Broker">Broker</link> is the principal entity. It is
+ composed on a number of other entities that colabrate together to provide message broker
+ facilities.</para>
+ <para>The Broker can only be managed via the HTTP management channel.</para>
+ <section id="Java-Broker-Management-Managing-Broker-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name the Broker</emphasis>. This helps distinguish between Brokers in
+ environments that have many.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Default Virtualhost</emphasis>. The default virtualhost is the one that
+ messaging clients will connect to if they do not specify a virtualhost name when they
+ form the connect to the Broker.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Heartbeating</emphasis>. Enables heartbeats between Broker and Clients.
+ Heartbeats help discover severed TCP/IP connections in a timely manner.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Broker-Context">
+ <title>Context</title>
+ <para>
+ <itemizedlist>
+ <listitem><para><emphasis>broker.flowToDiskThreshold</emphasis> Control the <link linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Broker-Children">
+ <title>Children</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes">Virtualhost
+ nodes</link></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Ports">Ports</link></para>
+ </listitem>
+ <listitem>
+ <para>Authentication Providers</para>
+ </listitem>
+ <listitem>
+ <para>Key Stores / Trust Stores</para>
+ </listitem>
+ <listitem>
+ <para>Group Providers</para>
+ </listitem>
+ <listitem>
+ <para>Access Control Providers</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Broker-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ </section>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,130 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Entities-Matrix">
+ <title>Entity/Management Channel Support Matrix</title>
+ <para>This tables indicates which management channels support the creation (C), update (U), or
+ deletion (D) of different entities within the Broker.</para>
+ <table frame="all">
+ <title>Entity/Management Matrix</title>
+ <tgroup cols="4" align="left" colsep="1" rowsep="1">
+ <colspec colname="entity"/>
+ <colspec colname="http"/>
+ <colspec colname="jmx"/>
+ <colspec colname="amqp"/>
+ <thead>
+ <row>
+ <entry>Entity</entry>
+ <entry>HTTP</entry>
+ <entry>JMX</entry>
+ <entry>AMQP</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Broker</entry>
+ <entry>U</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Virtualhost Node</entry>
+ <entry>C/U/D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Virtualhost</entry>
+ <entry>C/U/D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Remote Replication Node</entry>
+ <entry>U/D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Exchange</entry>
+ <entry>C/D</entry>
+ <entry>C/D</entry>
+ <entry>C/D</entry>
+ </row>
+ <row>
+ <entry>Queue</entry>
+ <entry>C/D</entry>
+ <entry>C/U/D</entry>
+ <entry>C/D</entry>
+ </row>
+ <row>
+ <entry>Binding</entry>
+ <entry>C/D</entry>
+ <entry>C/D</entry>
+ <entry>C/D</entry>
+ </row>
+ <row>
+ <entry>Port</entry>
+ <entry>C/U/D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Authentication Providers</entry>
+ <entry>C/U/D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Group Providers</entry>
+ <entry>C//D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Access Control Provider</entry>
+ <entry>C//D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Keystores</entry>
+ <entry>C//D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Truststores</entry>
+ <entry>C//D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <important>
+ <title>Note</title>
+ <para>It is currently only possible to modify a entity's context using the HTTP channel.
+ Furthermore, when using the JMX channel, it is not possible to assign non-String type
+ attributes in terms of context variables.</para>
+ </important>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,79 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Exchanges">
+ <title>Exchanges</title>
+ <para><link linkend="Java-Broker-Concepts-Exchanges">Exchanges</link> can be managed using the
+ HTTP, JMX or AMQP channels.</para>
+ <section id="Java-Broker-Management-Managing-Exchanges-Types">
+ <title>Types</title>
+ <para><itemizedlist>
+ <listitem>
+ <para>Direct</para>
+ </listitem>
+ <listitem>
+ <para>Topic</para>
+ </listitem>
+ <listitem>
+ <para>Fanout</para>
+ </listitem>
+ <listitem>
+ <para>Headers</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Exchanges-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name of the exchange</emphasis>. Message producers refer to this name when
+ producing messages.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Type of the exchange</emphasis>. Can be either <link
+ linkend="Java-Broker-Concepts-Exchanges-Types-Direct">direct</link>, <link
+ linkend="Java-Broker-Concepts-Exchanges-Types-Topic">topic</link>, <link
+ linkend="Java-Broker-Concepts-Exchanges-Types-Fanout">fanout</link>, or <link
+ linkend="Java-Broker-Concepts-Exchanges-Types-Headers">headers</link>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Durable</emphasis>. Whether the exchange survives a restart.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Exchanges-Children">
+ <title>Children</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>Binding</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Exchanges-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ </section>
+
+</section>
Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml)
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml Mon Oct 6 06:56:59 2014
@@ -20,7 +20,7 @@
-->
-<section id="Java-Broker-Configuring-And-Managing-Other-Tooling">
-<title>Other Tooling</title>
-
+<section id="Java-Broker-Management-Managing-Group-Providers">
+ <title>Group Providers</title>
+ <para>See <xref linkend="Java-Broker-Security-Group-Providers"/></para>
</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY % entities SYSTEM "../../commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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-Management-Managing-Keystores">
+ <title>Keystores</title>
+ <para>A <link linkend="Java-Broker-Concepts-Keystores">Keystore</link> is required by a Port
+ in order to use SSL.</para>
+ <section id="Java-Broker-Management-Managing-Keystores-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name the keystore</emphasis>. Used to identify the
+ keystore.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Path</emphasis>. Path to keystore file</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Keystore password</emphasis>. Password used to secure the keystore<important>
+ <para> The password of the certificate used by the Broker <emphasis
+ role="bold">must</emphasis> match the password of the keystore
+ itself. This is a restriction of the Qpid Broker implementation. If
+ using the <ulink url="&oracleKeytool;">keytool</ulink> utility, note
+ that this means the argument to the <option>-keypass</option> option
+ must match the <option>-storepass</option> option. </para>
+ </important></para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Certificate Alias</emphasis>. An optional way of specifying
+ which certificate the broker should use if the keystore contains multiple
+ entries.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Manager Factory Algorithm</emphasis>. In keystores the have more
+ than one certificate, the alias identifies the certificate to be
+ used.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Key Store Type</emphasis>. Type of Keystore.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Keystores-Children">
+ <title>Children</title>
+ <para>None</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Keystores-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ </section>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,63 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Plugin-HTTP">
+ <title>HTTP Plugin</title>
+ <para>The HTTP Plugin provides the <link linkend="Java-Broker-Management-Channel-HTTP">HTTP managenenent channel</link> comprising of the <link linkend="Java-Broker-Management-Channel-Web-Console">Web
+ Managemnt Console</link> and the <link linkend="Java-Broker-Management-Channel-REST-API">REST API</link>.</para>
+ <section id="Java-Broker-Management-Managing-Plugin-HTTP-Attributes">
+ <title>Attributes</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Basic Authentication for HTTP</emphasis>. It is set to false
+ (disabled) by default.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Basic Authentication for HTTPS</emphasis>. It is set to true
+ (enabled) by default.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>SASL Authentication for HTTP</emphasis>. It is set to true
+ (enabled) by default.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>SASL Authentication for HTTPS</emphasis>. It is set to true
+ (enabled) by default.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Session timeout</emphasis> is the timeout in seconds to close
+ the HTTP session. It is set to 10 minutes by default.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Plugin-HTTP-Children">
+ <title>Children</title>
+ <para>None</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Plugin-HTTP-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported<important><para>NOTE: Changes to the Session Timeout attribute only take
+ effect at broker restart. </para></important></para>
+ </section>
+</section>
Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml)
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml Mon Oct 6 06:56:59 2014
@@ -20,7 +20,10 @@
-->
-<section id="Java-Broker-Configuring-And-Managing-Other-Tooling">
-<title>Other Tooling</title>
-
+<section id="Java-Broker-Management-Managing-Plugins-JMX">
+ <title>JMX Plugin</title>
+ <para>
+ The JMX Plugin provides the <link linkend="Java-Broker-Management-Channel-JMX">JMX managenenent channel</link>.
+ </para>
+ <para>TODO</para>
</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,95 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-Ports">
+ <title>Ports</title>
+ <para>Ports provide TCP/IP connectivity for messaging and management. A port is defined to use a
+ protocol. This can be an AMQP protocol for messaging or HTTP/JMX for management.</para>
+ <para>A port is defined to have one or more transports. A transport can either be plain (TCP) or
+ SSL. When SSL is in use, the port can be configured to accept or require client
+ authentication.</para>
+ <para>Any number of ports defined to use AMQP or HTTP protocols can be defined. JMX is limited
+ to a single port instance per JMX protocol type.</para>
+ <para>Ports can only be managed by the HTTP management channel.</para>
+ <section id="Java-Broker-Management-Managing-Ports-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name the port</emphasis>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Port number</emphasis>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Binding address</emphasis>. Used to limit port binding to a
+ single network interface.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Authentication Provider</emphasis>. The <link
+ linkend="Java-Broker-Concepts-Authentication-Providers">authentication
+ provider</link> used to authenticate incoming connections.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Protocol(s)</emphasis>. A list of protocols to be supported by
+ the port. For messaging choose one or more AMQP protocols. For management
+ choose HTTP or on one the two JMX protocols.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Transports</emphasis>. A list of transports supported by the
+ port. For messaging or HTTP management chose TCP, SSL or both. For JMX, the
+ TCP/SSL combination is not supported.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Keystore</emphasis>. <link
+ linkend="Java-Broker-Management-Managing-Keystores">Keystore</link>
+ containing the Broker's private key. Required if the SSL is in use.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Want/Need Client Auth</emphasis>. Client authentication can be
+ either accepted if offered (want), or demanded (need). When Client
+ Certificate Authentication is in use a Truststore must be configured. When
+ using Client Certificate Authentication it may be desirable to use the <link
+ linkend="Java-Broker-Security-External-Provider">External Authentication
+ Provider</link>.</para>
+ <para>JMX does not support client authentication.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Truststore</emphasis>. <link
+ linkend="Java-Broker-Management-Managing-Truststores">Trust store</link>
+ contain an issuer certificate or the public keys of the clients themselves
+ if peers only is desired.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Ports-Children">
+ <title>Children</title>
+ <para>None</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Ports-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ <important>
+ <para>When updating an existing port, changes to SSL settings, binding address and port
+ numbers do not become effective until the Broker is restarted.</para>
+ </important>
+ </section>
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,324 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY % entities SYSTEM "../../commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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-Management-Managing-Queues">
+ <title>Queues</title>
+ <para><link linkend="Java-Broker-Concepts-Queues">Queue</link>s are named entities that
+ hold/buffer messages for later delivery to consumer applications.</para>
+ <para>Queues can be managed using the HTTP, JMX or AMQP channels.</para>
+ <section id="Java-Broker-Management-Managing-Queues-Types">
+ <title>Types</title>
+ <para>The Broker supports four different queue types, each with different delivery semantics.<itemizedlist>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Queues-Types-Standard"
+ >Standard</link> - a simple First-In-First-Out (FIFO) queue</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Queues-Types-Priority"
+ >Priority</link> - delivery order depends on the priority of each message</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Queues-Types-Sorted">Sorted</link> -
+ delivery order depends on the value of the sorting key property in each message</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="Java-Broker-Management-Managing-Queues-Types-LVQ">Last Value
+ Queue</link> - also known as an LVQ, retains only the last (newest) message received
+ with a given LVQ key value</para>
+ </listitem>
+ </itemizedlist></para>
+ <section id="Java-Broker-Management-Managing-Queues-Types-Standard">
+ <title>Standard</title>
+ <para>A simple First-In-First-Out (FIFO) queue</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-Types-Priority">
+ <title>Priority</title>
+ <para>In a priority queue, messages on the queue are delivered in an order determined by the
+ <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getJMSPriority()">JMS priority message
+ header</ulink> within the message. By default Qpid supports the 10 priority levels
+ mandated by JMS, with priority value 0 as the lowest priority and 9 as the highest. </para>
+ <para>It is possible to reduce the effective number of priorities if desired.</para>
+ <para>JMS defines the <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#DEFAULT_PRIORITY">
+ default message priority</ulink> as 4. Messages sent without a specified priority use this
+ default. </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-Types-Sorted">
+ <title>Sorted Queues</title>
+ <para>Sorted queues allow the message delivery order to be determined by value of an arbitrary
+ <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getStringProperty()">JMS message
+ property</ulink>. Sort order is alpha-numeric and the property value must have a type
+ java.lang.String.</para>
+ <para>Messages sent to a sorted queue without the specified JMS message property will be
+ inserted into the 'last' position in the queue.</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-Types-LVQ">
+ <title>Last Value Queues (LVQ)</title>
+ <para>LVQs (or conflation queues) are special queues that automatically discard any message
+ when a newer message arrives with the same key value. The key is specified by arbitrary
+ <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getPropertyNames()">JMS message
+ property</ulink>.</para>
+ <para>An example of an LVQ might be where a queue represents prices on a stock exchange: when
+ you first consume from the queue you get the latest quote for each stock, and then as new
+ prices come in you are sent only these updates. </para>
+ <para>Like other queues, LVQs can either be browsed or consumed from. When browsing an
+ individual subscriber does not remove the message from the queue when receiving it. This
+ allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and
+ bind a separate LVQ for each subscriber who wishes to receive the contents of the
+ LVQ).</para>
+ <para>Messages sent to an LVQ without the specified property will be delivered as normal and
+ will never be "replaced".</para>
+ </section>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name of the queue</emphasis>. Message consumers and browsers refer to this
+ name when they wish to subscribe to queue to receive messages from it.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Type of the queue</emphasis>. Can be either <link
+ linkend="Java-Broker-Management-Managing-Queues-Types-Standard">standard</link>, <link
+ linkend="Java-Broker-Management-Managing-Queues-Types-Priority">priority</link>, <link
+ linkend="Java-Broker-Management-Managing-Queues-Types-Sorted">sorted</link>, or <link
+ linkend="Java-Broker-Management-Managing-Queues-Types-LVQ">lvq</link>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Durable</emphasis>. Whether the queue survives a restart. Messages on a
+ non durable queue do not survive a restart even if they are marked persistent.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Maximum/Minimum TTL</emphasis>. Defines a maximum and minimum
+ time-to-live. Messages arriving with ttl larger than the maximum will be overridden by
+ the maximum. Similarly, messages arriving with tll less than the miniumum (or no ttl at
+ all), will be overridden by the minimum.</para>
+ <para>Changing these values affects only new arrivals, existing messages already on the
+ queue are not affected.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Message persistent override</emphasis>. Allow message persistent settings
+ of incoming messages to be overridden. Changing this value affects only new arrivals,
+ existing messages on the queue are not affected. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Queue capacity</emphasis>. Queues have the ability to limit the of the
+ cumulative size of all the messages contained within the store. This feature is
+ described in detail <xref linkend="Java-Broker-Runtime-Disk-Space-Management"/>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Alerting Thresholds</emphasis>. Queues have the ability to alert on a
+ variety of conditions: totol queue depth exceeded a number or size, message age exceeded
+ a threshold, message size exceeded a threshold. These thresholds are soft. See <xref
+ linkend="Java-Broker-Appendix-Queue-Alerts"/></para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Maximum Delivery Count/Alternate Exchange</emphasis>. See <xref
+ linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages"/></para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Message Groups</emphasis>. See <xref
+ linkend="Java-Broker-Management-Managing-Queues-Message-Grouping"/></para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queue-Children">
+ <title>Children</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>Binding</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queue-Lifecycle">
+ <title>Lifecycle</title>
+ <para>Not supported</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-QueueDeclareArguments">
+ <title>Queue Declare Arguments</title>
+ <para>To create a priority, sorted or LVQ queue programmatically from JMX or AMQP, pass the
+ appropriate queue-declare arguments.</para>
+ <table>
+ <title>Queue-declare arguments understood for priority, sorted and LVQ queues</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Queue type</entry>
+ <entry>Argument name</entry>
+ <entry>Argument name</entry>
+ <entry>Argument Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>priority</entry>
+ <entry>x-qpid-priorities</entry>
+ <entry>java.lang.Integer</entry>
+ <entry>Specifies a priority queue with given number priorities</entry>
+ </row>
+ <row>
+ <entry>sorted</entry>
+ <entry>qpid.queue_sort_key</entry>
+ <entry>java.lang.String</entry>
+ <entry>Specifies sorted queue with given message property used to sort the
+ entries</entry>
+ </row>
+ <row>
+ <entry>lvq</entry>
+ <entry>qpid.last_value_queue_key</entry>
+ <entry>java.lang.String</entry>
+ <entry>Specifies lvq queue with given message property used to conflate the
+ entries</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="Java-Broker-Management-Managing-Queues-Message-Grouping">
+ <title>Messaging Grouping</title>
+ <para> The broker allows messaging applications to classify a set of related messages as
+ belonging to a group. This allows a message producer to indicate to the consumer that a group
+ of messages should be considered a single logical operation with respect to the application. </para>
+ <para> The broker can use this group identification to enforce policies controlling how messages
+ from a given group can be distributed to consumers. For instance, the broker can be configured
+ to guarantee all the messages from a particular group are processed in order across multiple
+ consumers. </para>
+ <para> For example, assume we have a shopping application that manages items in a virtual
+ shopping cart. A user may add an item to their shopping cart, then change their mind and
+ remove it. If the application sends an <emphasis>add</emphasis> message to the broker,
+ immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the
+ proper order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>. </para>
+ <para> However, if there are multiple consumers, it is possible that once a consumer acquires
+ the <emphasis>add</emphasis> message, a different consumer may acquire the
+ <emphasis>remove</emphasis> message. This allows both messages to be processed in parallel,
+ which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly
+ performed before the <emphasis>add</emphasis> operation. </para>
+ <section id="Java-Broker-Management-Managing-Queues-GroupingMessages">
+ <title>Grouping Messages</title>
+ <para> In order to group messages, the application would designate a particular message header
+ as containing a message's <emphasis>group identifier</emphasis>. The group identifier stored
+ in that header field would be a string value set by the message producer. Messages from the
+ same group would have the same group identifier value. The key that identifies the header
+ must also be known to the message consumers. This allows the consumers to determine a
+ message's assigned group. </para>
+ <para> The header that is used to hold the group identifier, as well as the values used as
+ group identifiers, are totally under control of the application. </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-BrokerRole">
+ <title> The Role of the Broker in Message Grouping </title>
+ <para> The broker will apply the following processing on each grouped message: <itemizedlist>
+ <listitem>
+ <para>Enqueue a received message on the destination queue.</para>
+ </listitem>
+ <listitem>
+ <para>Determine the message's group by examining the message's group identifier
+ header.</para>
+ </listitem>
+ <listitem>
+ <para>Enforce <emphasis>consumption ordering</emphasis> among messages belonging to the
+ same group. <emphasis>Consumption ordering</emphasis> means one of two things
+ depending on how the queue has been configured. </para>
+ <itemizedlist>
+ <listitem>
+ <para> In default mode, a group gets assigned to a single consumer for the lifetime
+ of that consumer, and the broker will pass all subsequent messages in the group to
+ that consumer. </para>
+ </listitem>
+ <listitem>
+ <para>In 'shared groups' mode (which gives the same behaviour as the Qpid C++
+ Broker) the broker enforces a looser guarantee, namely that all the
+ <emphasis>currently unacknowledged messages</emphasis> in a group are sent to
+ the same consumer, but the consumer used may change over time even if the
+ consumers do not. This means that only one consumer can be processing messages
+ from a particular group at any given time, however if the consumer acknowledges
+ all of its acquired messages then the broker <emphasis>may</emphasis> pass the
+ next pending message in that group to a different consumer. </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para> The absence of a value in the designated group header field of a message is treated as
+ follows: <itemizedlist>
+ <listitem>
+ <para> In default mode, failure for a message to specify a group is treated as a desire
+ for the message not to be grouped at all. Such messages will be distributed to any
+ available consumer, without the ordering quarantees imposed by grouping. </para>
+ </listitem>
+ <listitem>
+ <para> In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker)
+ the broker assigns messages without a group value to a 'default group'. Therefore, all
+ such "unidentified" messages are considered by the broker as part of the same group,
+ which will handled like any other group. The name of this default group is
+ "qpid.no-group", although it can be customised as detailed below. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para> Note that message grouping has no effect on queue browsers.</para>
+ <para> Note well that distinct message groups would not block each other from delivery. For
+ example, assume a queue contains messages from two different message groups - say group "A"
+ and group "B" - and they are enqueued such that "A"'s messages are in front of "B". If the
+ first message of group "A" is in the process of being consumed by a client, then the
+ remaining "A" messages are blocked, but the messages of the "B" group are available for
+ consumption by other consumers - even though it is "behind" group "A" in the queue. </para>
+ </section>
+
+ </section>
+ <section id="Java-Broker-Management-Managing-Queues-SetLowPrefetch">
+ <title>Using low pre-fetch with special queue types</title>
+ <para>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value.
+ The current default is 500. </para>
+ <para>However, if you use the default value you will probably <emphasis>not</emphasis> see
+ desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has
+ sent a message to the client its delivery order is then fixed, regardless of the special
+ behaviour of the queue. </para>
+ <para>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with
+ priority 2, the broker will send these messages to the client. If then a new message arrives
+ will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will
+ be delivered at the front of the next batch of messages to be sent to the client.</para>
+ <para> So, you need to set the prefetch values for your client (consumer) to make this sensible.
+ To do this set the Java system property <varname>max_prefetch</varname> on the client
+ environment (using -D) before creating your consumer. </para>
+ <para>A default for all client connections can be set via a system property: </para>
+ <programlisting>
+-Dmax_prefetch=1
+</programlisting>
+ <para> The prefetch can be also be adjusted on a per connection basis by adding a
+ <varname>maxprefetch</varname> value to the <ulink url="&qpidjmsdocClientConectionUrl;"
+ >Connection URLs</ulink>
+ </para>
+ <programlisting>
+amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672'
+</programlisting>
+ <para>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the
+ client however, this brings a performance cost. You could test with a slightly higher
+ pre-fetch to trade-off between throughput and exact semantics.</para>
+ </section>
+
+
+</section>
Added: qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml?rev=1629579&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml Mon Oct 6 06:56:59 2014
@@ -0,0 +1,112 @@
+<?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.
+
+-->
+
+<section id="Java-Broker-Management-Managing-RemoteReplicationNodes">
+ <title>Remote Replication Nodes</title>
+ <para>Used for HA only. A <link linkend="Java-Broker-Concepts-RemoteReplicationNodes">remote replication node</link> is a representation of another virtualhost node
+ in the group. Remote replication nodes are not created directly. Instead the system
+ automatically creates a remote replciation node for every node in the group. It serves to
+ provide a view of the whole group from every node in the system.</para>
+ <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Attributes">
+ <title>Attributes</title>
+ <para><itemizedlist>
+ <listitem>
+ <para><emphasis>Name the remote replication node</emphasis>. This is the name of the
+ remote virtualhost node</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Role</emphasis>. Indicates the role that the remote node is playing in the
+ group at this moment. <itemizedlist>
+ <listitem>
+ <para><emphasis>MASTER</emphasis> - Remote node is a master.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>REPLICA</emphasis> - Remote node is a replica.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>UNREACHABLE</emphasis> - Remote node unreachanble from this node.
+ This remote note may be down, or an network problem may prevent it from being
+ contacted.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Join time</emphasis>. Time when first contact was established with this
+ node.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Last known transaction id</emphasis>. Last transaction id reported
+ processed by node. This is an internal transaction counter and does not relate to any
+ value available to the messaging clients. This value can only be used to determine the
+ node is up to date relative to others in the group.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Children">
+ <title>Children</title>
+ <para>None</para>
+ </section>
+ <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Lifecycle">
+ <title>Lifecycle</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Delete</emphasis>. Causes the remote node to be permanently removed from
+ the group. This operation should be used when the virtualhost node cannot be deleted
+ from its own Broker, for instance, if a Broker has been destroyed by machine
+ failure.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Managing-RemoteReplication-Nodes-Operations">
+ <title>Operations</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Transfer Master</emphasis>. Initiates a process where a master is moved to
+ anther node in the group. The transfer sequence is as follows. <orderedlist>
+ <listitem>
+ <para>Group waits until the proposed master is reasonable up to date.</para>
+ </listitem>
+ <listitem>
+ <para>Any in-flight transactions on the current master are blocked.</para>
+ </listitem>
+ <listitem>
+ <para>The current master awaits the proposed master to become up to date.</para>
+ </listitem>
+ <listitem>
+ <para>The mastership is transfered. This will automatically disconnect messaging
+ clients from the old master, and in-flight transactions are rolled back. Messaging
+ clients reconnect to the new master.</para>
+ </listitem>
+ <listitem>
+ <para>The old master will rejoin as a replica.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org