qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kw...@apache.org
Subject svn commit: r1631830 - in /qpid/trunk/qpid/doc/book/src/java-broker: ./ concepts/ images/ management/channels/ management/managing/
Date Tue, 14 Oct 2014 17:41:50 GMT
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}/&lt;nodename&gt;/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}/&lt;nodename&gt;/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}/&lt;nodename&gt;/config -todir
-          path/to/backup/folder</command>
+        <cmdsynopsis>
+          <command>backup.sh</command>
+          <arg choice="plain">-fromdir <replaceable>${QPID_WORK}/&lt;nodename&gt;/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}/&lt;nodename&gt;/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/&lt;version&gt;</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/&lt;vhost node&gt;/&lt;vhost&gt;/&lt;exchange&gt;/&lt;queue&gt;/&lt;binding&gt;
-    replacing of <emphasis>&lt;exchange&gt;</emphasis> with "asterisks"
-    (http://localhost:8080/api/&lt;ver&gt;/binding/&lt;vhost node&gt;/&lt;vhost&gt;/*/&lt;queue&gt;/&lt;binding&gt;)
-    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>&lt;binding&gt;</emphasis>
and
-      <emphasis>&lt;queue&gt;</emphasis> are omitted in binding REST
URL
-    (http://localhost:8080/api/&lt;ver&gt;/binding/&lt;vhost node&gt;/&lt;vhost&gt;/&lt;exchangename&gt;)
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/&lt;vhost
+      node&gt;/&lt;vhost&gt;/&lt;exchange&gt;/&lt;queue&gt;/&lt;binding&gt;</literal>
replacing of
+      <literal>&lt;exchange&gt;</literal> with "asterisks"
+      (<literal>http://localhost:8080/api/&lt;ver&gt;/binding/&lt;vhost
+      node&gt;/&lt;vhost&gt;/*/&lt;queue&gt;/&lt;binding&gt;</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>&lt;binding&gt;</literal> and <literal>&lt;queue&gt;</literal>
are omitted in
+    binding REST URL (<literal>http://localhost:8080/api/&lt;ver&gt;/binding/&lt;vhost
+      node&gt;/&lt;vhost&gt;/&lt;exchangename&gt;</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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message