From dd256e5f6aa598bde97dcc6236d5cb6417add5ba Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Tue, 14 Oct 2014 17:41:50 +0000 Subject: QPID-6108: [Java Broker Documentation] Address some comments from Andrew Macbean git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1631830 13f79535-47bb-0310-9956-ffa450edef68 --- .../Java-Broker-Backup-And-Recovery.xml | 20 +++++--- .../java-broker/Java-Broker-High-Availability.xml | 56 ++++++++++++--------- .../Java-Broker-Concepts-Virtualhost-Nodes.xml | 2 +- .../images/Management-Web-Add-Dialogue.png | Bin 69379 -> 70733 bytes .../images/Management-Web-ContextVar.png | Bin 27262 -> 29470 bytes .../Java-Broker-Management-Channel-REST-API.xml | 28 +++++------ .../Java-Broker-Management-Channel-Web-Console.xml | 23 +++++---- .../Java-Broker-Management-Managing-Broker.xml | 2 +- .../Java-Broker-Management-Managing-Queues.xml | 2 +- 9 files changed, 77 insertions(+), 56 deletions(-) (limited to 'qpid/doc/book/src/java-broker') diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml b/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml index 670fc04829..09bb2b4fcc 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Backup-And-Recovery.xml @@ -55,9 +55,14 @@ Performing store backup by using <classname>BDBBackup</classname> class directly - java -cp qpid-bdbstore-&qpidCurrentRelease;.jar - org.apache.qpid.server.store.berkeleydb.BDBBackup -fromdir - ${QPID_WORK}/<nodename>/config -todir path/to/backup/folder + + java + -cp qpid-bdbstore-&qpidCurrentRelease;.jar + org.apache.qpid.server.store.berkeleydb.BDBBackup + + -fromdir ${QPID_WORK}/<nodename>/config + -todir path/to/backup/folder + 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. Performing store backup by using <classname>backup.sh</classname> bash script - backup.sh -fromdir ${QPID_WORK}/<nodename>/config -todir - path/to/backup/folder + + backup.sh + -fromdir ${QPID_WORK}/<nodename>/config + -todir path/to/backup/folder +
- BDB + BDB-HA See
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml index 9dfbbaf764..25c56a8d14 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml @@ -116,8 +116,8 @@ 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. + arbitrary one. The node is special only whilst creating group. Once creation is + complete, all nodes will be considered equal. @@ -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. - Repeat these steps until you have added all the nodes to the - group. + + Repeat these steps until you have added all the nodes to the group. +
- Adding subsequent nodes to the group + Adding subsequent nodes to the group @@ -261,8 +262,8 @@ 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. 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. - 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. + 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. 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. - 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 split-brain will occur. + + 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 split-brain will + occur.
@@ -434,9 +437,9 @@ Delete - 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. + 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. The names of deleted virtualhost node cannot be reused within a group. @@ -485,8 +488,8 @@
Qpid JMX API for HA - The Qpid JMX API for HA is now deprecated. New users are recommended to use the REST - API. + The Qpid JMX API for HA is now deprecated. New users are recommended to use the REST API.
@@ -541,14 +544,21 @@ provided information. Resetting of replication group with <classname>DbResetRepGroup</classname> - java -cp je-&oracleBdbProductVersion;.jar com.sleepycat.je.rep.util.DbResetRepGroup - -h path/to/jelogfiles -groupName newgroupname -nodeName nodename -nodeHostPort - thor:5000 + + java + -cp je-&oracleBdbProductVersion;.jar + com.sleepycat.je.rep.util.DbResetRepGroup + -h path/to/jelogfiles + + -groupName newgroupname + -nodeName newnodename + -nodeHostPort newhostname:5000 + The modified log files can then by copied into ${QPID_WORK}/<nodename>/config 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.
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml index 064c44b22f..c1dd903aed 100644 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml @@ -27,7 +27,7 @@ A virtualhost node is backed by storage. This storage is used to record the durable entities that exist beneath the virtualhost node (the virtualhost, queues, exchanges etc). - When HA is in used, it is the virtualhost nodes of many Brokers that come together to form + 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 remote replications nodes. There is a remote replication node corresponding to each diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png b/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png index a2d6b4c690..b476060daa 100644 Binary files a/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png and b/qpid/doc/book/src/java-broker/images/Management-Web-Add-Dialogue.png differ diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png b/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png index 92626e092e..3c62bc9f6e 100644 Binary files a/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png and b/qpid/doc/book/src/java-broker/images/Management-Web-ContextVar.png differ diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml index 94c7039819..76fe0974f9 100644 --- a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml @@ -23,7 +23,7 @@
REST API This section provides a brief overview of the REST interface, which can be used directly to - monitor and manage the Broker instance.. + monitor and manage the Broker instance. 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 @@ The REST API is versioned with the version number built into the URL. The general form of the URL is /api/<version>. For convenience the alias latest signifies the latest supported version. There are also some - ancillary service prefixed by /service. + ancillary services prefixed by /service. The table below lists the available REST services with brief description how they can be used. @@ -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. - For example, for binding URL - http://localhost:8080/api/latest/binding/<vhost node>/<vhost>/<exchange>/<queue>/<binding> - replacing of <exchange> 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 <binding> and - <queue> 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. + For example, for binding URL http://localhost:8080/api/latest/binding/<vhost + node>/<vhost>/<exchange>/<queue>/<binding> replacing of + <exchange> 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 <binding> and <queue> 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. Examples of queue creation using curl (authenticating as user admin): 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 + off by default). For details see
diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml index b3223d3109..d9f141f01a 100644 --- a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml @@ -54,7 +54,8 @@ Web Management Console - Authentication - + Web Console Authentication @@ -71,7 +72,7 @@ + width="900px"/> The Web Console @@ -110,7 +111,8 @@ Web Management Orientation - Tab - + A tab within the Web Consle @@ -148,9 +150,9 @@ dialogue to be displayed. 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. + 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.
Web Management Orientation - Add Dialogue @@ -159,7 +161,7 @@ scalefit="1"/> - Example add dialogue + Example add dialogue showing field level help
@@ -200,7 +202,8 @@ 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. -
+
Web Management Orientation - Context Variables @@ -212,14 +215,14 @@
- You will see any context varaiables already associated with the object, called + 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. 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. The + button allows new variables to be added. The - - button removes existing one. + - button removes existing ones. You change an existing local variables defintion by clicking on the actual value. You can also provide a local definition for an inherited value by clicking on the actual value and typing its new value. diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml index b5c231046e..54e9d81ff1 100644 --- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml @@ -23,7 +23,7 @@
Broker The Broker 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. The Broker can only be managed via the HTTP management channel.
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml index ffa384403c..66755f718f 100644 --- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml @@ -26,7 +26,7 @@
Queues - Queues are named entities that + Queues are named entities that hold/buffer messages for later delivery to consumer applications. Queues can be managed using the HTTP, JMX or AMQP channels.
-- cgit v1.2.1