Author: kwall
Date: Tue Oct 14 17:41:50 2014
New Revision: 1631830
URL: http://svn.apache.org/r1631830
Log:
QPID-6108: [Java Broker Documentation] Address some comments from Andrew Macbean
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml?rev=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml
Tue Oct 14 17:41:50 2014
@@ -55,9 +55,14 @@
<example>
<title>Performing store backup by using
<classname>BDBBackup</classname> class
directly</title>
- <command> java -cp qpid-bdbstore-&qpidCurrentRelease;.jar
- org.apache.qpid.server.store.berkeleydb.BDBBackup -fromdir
- ${QPID_WORK}/<nodename>/config -todir
path/to/backup/folder</command>
+ <cmdsynopsis>
+ <command>java</command>
+ <arg choice="plain">-cp qpid-bdbstore-&qpidCurrentRelease;.jar</arg>
+ <arg
choice="plain">org.apache.qpid.server.store.berkeleydb.BDBBackup</arg>
+ <sbr/>
+ <arg choice="plain">-fromdir
<replaceable>${QPID_WORK}/<nodename>/config</replaceable></arg>
+ <arg choice="plain">-todir
<replaceable>path/to/backup/folder</replaceable></arg>
+ </cmdsynopsis>
</example>
<para>In the example above BDBBackup utility is called from
qpid-bdbstore-&qpidCurrentRelease;.jar to backup the store at
@@ -67,12 +72,15 @@
running this script in a similar way.</para>
<example>
<title>Performing store backup by using
<classname>backup.sh</classname> bash script</title>
- <command>backup.sh -fromdir ${QPID_WORK}/<nodename>/config -todir
- path/to/backup/folder</command>
+ <cmdsynopsis>
+ <command>backup.sh</command>
+ <arg choice="plain">-fromdir
<replaceable>${QPID_WORK}/<nodename>/config</replaceable></arg>
+ <arg choice="plain">-todir
<replaceable>path/to/backup/folder</replaceable></arg>
+ </cmdsynopsis>
</example>
</section>
<section id="Java-Broker-Backup-And-Recovery-Virtualhost-Node-BDB-HA">
- <title>BDB</title>
+ <title>BDB-HA</title>
<para>See <xref
linkend="Java-Broker-Backup-And-Recovery-Virtualhost-Node-BDB"/></para>
</section>
<section id="Java-Broker-Backup-And-Recovery-Virtualhost-Node-Derby">
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml?rev=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
Tue Oct 14 17:41:50 2014
@@ -116,8 +116,8 @@
</listitem>
<listitem>
<para>Select one Broker instance to host the first node instance.
This choice is an
- arbitrary one. The node is special only whilst creating group.
Once creation is complete,
- all nodes will be considered equal.</para>
+ arbitrary one. The node is special only whilst creating group.
Once creation is
+ complete, all nodes will be considered equal.</para>
</listitem>
<listitem>
<para>
@@ -198,12 +198,13 @@
contact it and introduce itself into the group. At this
stage, the group will have
two nodes, with the second node in the replica role.</para>
</listitem>
- <listitem>Repeat these steps until you have added all the nodes
to the
- group.</listitem>
+ <listitem>
+ <para>Repeat these steps until you have added all the nodes to
the group.</para>
+ </listitem>
</orderedlist>
<para>
<figure>
- <title>Adding subsequent nodes to the group</title>
+ <title>Adding subsequent nodes to the group</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/HA-Create-2.png" format="PNG"
scalefit="1"/>
@@ -261,8 +262,8 @@
</listitem>
</itemizedlist></para>
<para>If there were to be a master failure immediately after the
transaction was committed,
- the transaction would be held by at least quorum minus one replicas.
For example, if we
- had a group of three, then we would be assured that at least one
replica held the
+ the transaction would be held by at least quorum minus one replicas.
For example, if we had
+ a group of three, then we would be assured that at least one replica
held the
transaction.</para>
<para>In the event of a master failure, if quorum nodes remain, those
nodes hold an election.
@@ -273,9 +274,9 @@
fewer than quorum nodes and to influence which node gets elected in
the event of a
tie.</para>
- <para>Whenever a group has fewer than quorum nodes present, the
virtualhost will be unavailable
- and messaging connections will be refused. If quorum disappears at the
very moment a
- messaging client sends a transaction that transaction will fail.</para>
+ <para>Whenever a group has fewer than quorum nodes present, the
virtualhost will be
+ unavailable and messaging connections will be refused. If quorum
disappears at the very
+ moment a messaging client sends a transaction that transaction will
fail.</para>
<para>You will have noticed the difference in the synchronization
policies applied the master
and the replicas. The replicas send the acknowledgement back before
the data is written to
@@ -392,9 +393,11 @@
as the remaining node cannot elect itself master. To allow it to
become master, apply the
designated primary flag to it. It will elect itself master and work
can continue, albeit
from one node.</para>
- <important>It is imperative not to allow designated primary to be set on
both nodes at once.
- To do so will mean, in the event of a network partition, a <ulink
-
url="http://en.wikipedia.org/wiki/Split-brain_(computing)">split-brain</ulink>
will occur.
+ <important>
+ <para>It is imperative not to allow designated primary to be set on
both nodes at once. To
+ do so will mean, in the event of a network partition, a <ulink
+
url="http://en.wikipedia.org/wiki/Split-brain_(computing)">split-brain</ulink>
will
+ occur.</para>
</important>
</section>
</section>
@@ -434,9 +437,9 @@
</listitem>
<listitem>
<para><emphasis>Delete</emphasis></para>
- <para>A virtualhost node can be deleted. Deleting a node permanently
removes the node
- from the group. The data stored locally is removed but this does
not affect the data
- held by the remainder of the group.</para>
+ <para>A virtualhost node can be deleted. Deleting a node permanently
removes the node from
+ the group. The data stored locally is removed but this does not
affect the data held by
+ the remainder of the group.</para>
<note>
<para>The names of deleted virtualhost node cannot be reused
within a group.</para>
</note>
@@ -485,8 +488,8 @@
</section>
<section role="h3" id="Java-Broker-High-Availability-JMXAPI">
<title>Qpid JMX API for HA</title>
- <para>The Qpid JMX API for HA is now deprecated. New users are recommended
to use the REST
- API.</para>
+ <para>The Qpid JMX API for HA is now deprecated. New users are recommended
to use the <link
+ linkend="Java-Broker-Management-Channel-REST-API">REST
API.</link></para>
</section>
<section id="Java-Broker-High-Availability-DiskSpace">
@@ -541,14 +544,21 @@
provided information. </para>
<example>
<title>Resetting of replication group with
<classname>DbResetRepGroup</classname></title>
- <command>java -cp je-&oracleBdbProductVersion;.jar
com.sleepycat.je.rep.util.DbResetRepGroup
- -h path/to/jelogfiles -groupName newgroupname -nodeName nodename
-nodeHostPort
- thor:5000</command>
+ <cmdsynopsis>
+ <command>java</command>
+ <arg choice="plain">-cp je-&oracleBdbProductVersion;.jar</arg>
+ <arg choice="plain">com.sleepycat.je.rep.util.DbResetRepGroup</arg>
+ <arg choice="plain">-h
<replaceable>path/to/jelogfiles</replaceable></arg>
+ <sbr/>
+ <arg choice="plain">-groupName
<replaceable>newgroupname</replaceable></arg>
+ <arg choice="plain">-nodeName
<replaceable>newnodename</replaceable></arg>
+ <arg choice="plain">-nodeHostPort
<replaceable>newhostname:5000</replaceable></arg>
+ </cmdsynopsis>
</example>
<para>The modified log files can then by copied into
<literal>${QPID_WORK}/<nodename>/config</literal> directory of a
target Broker. Then
- start the Broker, and add a BDB HA Virtualhost node specify the same
group name, node name
- and node address. You will then have a group with a single node, ready
to start re-adding
+ start the Broker, and add a BDB HA Virtualhost node specify the same
group name, node name and
+ node address. You will then have a group with a single node, ready to
start re-adding
additional nodes as described above. </para>
</section>
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml?rev=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml
Tue Oct 14 17:41:50 2014
@@ -27,7 +27,7 @@
<para>A <emphasis>virtualhost node</emphasis> is backed by storage. This
storage is used to record
the durable entities that exist beneath the virtualhost node (the
virtualhost, queues, exchanges
etc).</para>
- <para>When HA is in used, it is the virtualhost nodes of many Brokers that
come together to form
+ <para>When HA is in use, it is the virtualhost nodes of many Brokers that
come together to form
the group. The virtualhost nodes together elect a master. When the high
availability feature is
in use, the virtualhost node has <link
linkend="Java-Broker-Concepts-RemoteReplicationNodes"
>remote replications nodes</link>. There is a remote replication node
corresponding to each
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png?rev=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
Files
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png
(original) and
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png
Tue Oct 14 17:41:50 2014 differ
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png?rev=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
Files
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png
(original) and
qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png
Tue Oct 14 17:41:50 2014 differ
Modified:
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=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
Tue Oct 14 17:41:50 2014
@@ -23,7 +23,7 @@
<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>
+ 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
@@ -32,7 +32,7 @@
<para>The REST API is versioned with the version number built into the URL.
The general form of
the URL is <literal>/api/<version></literal>. For convenience the
alias
<literal>latest</literal> signifies the latest supported version. There
are also some
- ancillary service prefixed by <literal>/service</literal>.</para>
+ ancillary services prefixed by <literal>/service</literal>.</para>
<para>The table below lists the available REST services with brief
description how they can be
used.</para>
@@ -321,16 +321,17 @@
"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>
+ <para>For example, for binding URL
<literal>http://localhost:8080/api/latest/binding/<vhost
+
node>/<vhost>/<exchange>/<queue>/<binding></literal>
replacing of
+ <literal><exchange></literal> with "asterisks"
+ (<literal>http://localhost:8080/api/<ver>/binding/<vhost
+ node>/<vhost>/*/<queue>/<binding></literal>) 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.</para>
+ <para>If <literal><binding></literal> and
<literal><queue></literal> are omitted in
+ binding REST URL
(<literal>http://localhost:8080/api/<ver>/binding/<vhost
+ node>/<vhost>/<exchangename></literal>) 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[
@@ -348,7 +349,6 @@ curl --user admin -X PUT -d '{}' http:/
</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"/>
+ off by default). For details see <xref
linkend="Java-Broker-Management-Managing-Plugin-HTTP"/>
</para>
</section>
Modified:
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=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
Tue Oct 14 17:41:50 2014
@@ -54,7 +54,8 @@
<title>Web Management Console - Authentication</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Management-Web-Auth.png"
format="PNG" scalefit="1"/>
+ <imagedata fileref="images/Management-Web-Auth.png"
format="PNG" scalefit="1"
+ width="900px"/>
</imageobject>
<textobject>
<phrase>Web Console Authentication</phrase>
@@ -71,7 +72,7 @@
<mediaobject>
<imageobject>
<imagedata fileref="images/Management-Web-Console.png"
format="PNG" scalefit="1"
- />
+ width="900px"/>
</imageobject>
<textobject>
<phrase>The Web Console</phrase>
@@ -110,7 +111,8 @@
<title>Web Management Orientation - Tab</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Management-Web-Tab.png"
format="PNG" scalefit="1"/>
+ <imagedata fileref="images/Management-Web-Tab.png"
format="PNG" scalefit="1"
+ width="900px"/>
</imageobject>
<textobject>
<phrase>A tab within the Web Consle</phrase>
@@ -148,9 +150,9 @@
dialogue to be displayed.</para>
<para>Add dialogues allow you to set the attributes of the new
child, and set context
variables. Most fields on the add dialogue have field level
help that give more
- details about the attribute and any default value that will
take effect if you leave
- the attribute unset. An example add dialogue is shown in the
figure that
- follows.</para>
+ details about the attribute and any default value (which may
be expressed in terms
+ of a context variable) that will take effect if you leave the
attribute unset. An
+ example add dialogue is shown in the figure that
follows.</para>
<figure
id="Java-Broker-Management-Channel-Web-Console-Managing-Entities-Add-Dialogue">
<title>Web Management Orientation - Add Dialogue</title>
<mediaobject>
@@ -159,7 +161,7 @@
scalefit="1"/>
</imageobject>
<textobject>
- <phrase>Example add dialogue</phrase>
+ <phrase>Example add dialogue showing field level
help</phrase>
</textobject>
</mediaobject>
</figure>
@@ -200,7 +202,8 @@
<para>Most add and edit dialogues have the ability to make context
variable assignments.
To add/change/remove a context variable, click the Context
Variable panel to expand
it.</para>
- <figure
id="Java-Broker-Management-Channel-Web-Console-Managing-Entities-Context-Variables-Dialogue">
+ <figure
+
id="Java-Broker-Management-Channel-Web-Console-Managing-Entities-Context-Variables-Dialogue">
<title>Web Management Orientation - Context Variables</title>
<mediaobject>
<imageobject>
@@ -212,14 +215,14 @@
</textobject>
</mediaobject>
</figure>
- <para>You will see any context varaiables already associated with
the object, called
+ <para>You will see any context variables already associated with
the object, called
local context variables in bold, and any inherited from above
in normal face.</para>
<para>Since context variables can be defined in terms of other
context variables, the
display has two value columns: actual and effective. Actual
shows the value truely
associated with the variable, where as effective shows the
resulting value, after
variable expansion has taken place.</para>
<para>The <literal>+</literal> button allows new variables to be
added. The
- <literal>-</literal> button removes existing one.</para>
+ <literal>-</literal> button removes existing ones.</para>
<para>You change an existing local variables defintion by clicking
on the actual value.
You can also <emphasis>provide a local definition</emphasis>
for an inherited value
by clicking on the actual value and typing its new
value.</para>
Modified:
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=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
Tue Oct 14 17:41:50 2014
@@ -23,7 +23,7 @@
<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 collaborate to provide message
broker
+ composed of a number of other entities that collaborate 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">
Modified:
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=1631830&r1=1631829&r2=1631830&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml
Tue Oct 14 17:41:50 2014
@@ -26,7 +26,7 @@
<section id="Java-Broker-Management-Managing-Queues">
<title>Queues</title>
- <para><link linkend="Java-Broker-Concepts-Queues">Queue</link>s are named
entities that
+ <para><link linkend="Java-Broker-Concepts-Queues">Queues</link> 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">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
