You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/06/20 00:15:13 UTC
svn commit: r956304 [2/33] - in /qpid/site/docs/books/0.7: ./
AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html-single/
AMQP-Messaging-Broker-CPP-Book/html-single/images/
AMQP-Messaging-Broker-CPP-Book/html-single/images/jmx_console/ ...
Added: qpid/site/docs/books/0.7/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html (added)
+++ qpid/site/docs/books/0.7/AMQP-Messaging-Broker-CPP-Book/html-single/AMQP-Messaging-Broker-CPP-Book.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,4659 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AMQP Messaging Broker (Implemented in C++)</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AMQP Messaging Broker (Implemented in C++)"><div class="titlepage"><div><div><h1 class="title"><a name="id2496698"></a>AMQP Messaging Broker (Implemented in C++)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id2742037"></a></span></dt><dt><span class="chapter"><a href="#id2742093">1.
+ Running the AMQP Messaging Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#section-Running-a-Qpid-CPP-Broker">1.
+ Running a Qpid C++ Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#RASC-BuildingtheCppBrokerandClientLibraries">1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </a></span></dt><dt><span class="section"><a href="#RASC-RunningtheCppBroker">1.2.
+ Running the C++ Broker
+ </a></span></dt><dt><span class="section"><a href="#RASC-Mostcommonquestionsgettingqpiddrunning">1.3.
+ Most
+ common questions getting qpidd running
+ </a></span></dt><dt><span class="section"><a href="#RASC-Authentication">1.4.
+ Authentication
+ </a></span></dt><dt><span class="section"><a href="#RASC-Slightlymorecomplexconfiguration">1.5.
+ Slightly more
+ complex configuration
+ </a></span></dt><dt><span class="section"><a href="#RASC-Loadingextramodules">1.6.
+ Loading extra modules
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2494687">2.
+ Cheat Sheet for configuring Queue Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions">2.1.
+ Configuring
+ Queue Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2742008">3.
+ Cheat Sheet for configuring Exchange Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">3.1.
+ Configuring Exchange Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2743074">4.
+ Using Broker Federation
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#UsingBrokerFederation-Introduction">4.1.
+ Introduction
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-WhatIsBrokerFederation-3F">4.2.
+ What Is
+ Broker Federation?
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-TheqpidrouteUtility">4.3.
+ The
+ qpid-route Utility
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-ExampleScenarios">4.4.
+ Example
+ Scenarios
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-AdvancedTopics">4.5.
+ Advanced
+ Topics
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2744550">5.
+ SSL
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#SSL-SSLHowto">5.1.
+ SSL How to
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2743638">6.
+ LVQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#LVQ-UnderstandingLVQ">6.1.
+ Understanding LVQ
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQsemantics-3A">6.2.
+ LVQ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQNOBROWSEsemantics-3A">6.3.
+ LVQ_NO_BROWSE
+ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-Examplesource">6.4.
+ LVQ Program Example
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#queue-state-replication">7.
+ Queue State Replication
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#queuestatereplication-AsynchronousReplicationofQueueState">7.1.
+ Asynchronous
+ Replication of Queue State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2745445">8.
+ Starting a cluster
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#Startingacluster-RunningaQpiddcluster">8.1.
+ Running a
+ Qpidd cluster
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#qpid_ACL">9.
+ ACL
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ACL-v2ACLfileformatforbrokers">9.1.
+ v2 ACL file format for brokers
+ </a></span></dt><dt><span class="section"><a href="#ACL-DesignDocumentation">9.2.
+ Design Documentation
+ </a></span></dt><dt><span class="section"><a href="#ACL-v2ACLUserGuide">9.3.
+ v2 ACL User Guide
+ </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chapter-Managing-CPP-Broker">3.
+ Managing the AMQP Messaging Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#section-Managing-CPP-Broker">1. Managing the C++ Broker </a></span></dt><dd><dl><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidconfig">1.1.
+ Using qpid-config
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidroute">1.2.
+ Using qpid-route
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidtool">1.3.
+ Using qpid-tool
+ </a></span></dt><dt><span class="section"><a href="#MgmtC-2B-2B-Usingqpidprintevents">1.4.
+ Using
+ qpid-printevents
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2747148">2.
+ Qpid Management Framework
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidManagementFramework-WhatIsQMF">2.1.
+ What Is QMF
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-GettingStartedwithQMF">2.2.
+ Getting
+ Started with QMF
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-QMFConcepts">2.3.
+ QMF Concepts
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-TheQMFProtocol">2.4.
+ The QMF
+ Protocol
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-HowtoWriteaQMFConsole">2.5.
+ How
+ to Write a QMF Console
+ </a></span></dt><dt><span class="section"><a href="#QpidManagementFramework-HowtoWriteaQMFAgent">2.6.
+ How to
+ Write a QMF Agent
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2744546">3.
+ QMF Python Console Tutorial
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QMFPythonConsoleTutorial-PrerequisiteInstallQpidMessaging">3.1.
+ Prerequisite
+ - Install Qpid Messaging
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-SynchronousConsoleOperations">3.2.
+ Synchronous
+ Console Operations
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-AsynchronousConsoleOperations">3.3.
+ Asynchronous
+ Console Operations
+ </a></span></dt><dt><span class="section"><a href="#QMFPythonConsoleTutorial-DiscoveringwhatKindsofObjectsareAvailable">3.4.
+ Discovering what Kinds of Objects are Available
+ </a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>1.1. <a href="#id2744840">Transport Options for Federation</a></dt><dt>1.2. <a href="#id2745769">ACL Support in Qpid Broker Versions</a></dt><dt>1.3. <a href="#id2746276">Mapping ACL Traps</a></dt><dt>1.4. <a href="#id2747785">Mapping Management Actions to ACL</a></dt><dt>2.1. <a href="#id2746346">AMQP Version Support by Qpid Release</a></dt><dt>2.2. <a href="#id2748549">AMQP Version Support - alternate format</a></dt><dt>3.1. <a href="#id2749344">XML Attributes for QMF Properties and Statistics</a></dt><dt>3.2. <a href="#id2750788">QMF Datatypes</a></dt><dt>3.3. <a href="#id2751063">XML Schema Mapping for QMF Types</a></dt><dt>3.4. <a href="#id2752359">QMF Python Console Class Methods</a></dt></dl></div><div class="preface"><div class="titlepage"></div><p>Qpid provides two AMQP messaging brokers:</p><div class="itemizedlist"><ul class="itemizedlist" type=
"disc"><li class="listitem"><p>Implemented in C++ - high performance, low latency, and RDMA support.</p></li><li class="listitem"><p>Implemented in Java - Fully JMS compliant, runs on any Java platform.</p></li></ul></div><p>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <a class="link" href="#AMQP-Compatibility" title="Chapter 2. AMQP compatibility">AMQP Compatibility</a> to see which messaging clients work with each broker.</p><p>This manual contains information specific to the broker that is implemented in C++.</p></div><div class="chapter" title="Chapter 1. Running the AMQP Messaging Broker"><div class="titlepage"><div><div><h2 class="title"><a name="id2742093"></a>Chapter 1.
+ Running the AMQP Messaging Broker
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#section-Running-a-Qpid-CPP-Broker">1.
+ Running a Qpid C++ Broker
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#RASC-BuildingtheCppBrokerandClientLibraries">1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </a></span></dt><dt><span class="section"><a href="#RASC-RunningtheCppBroker">1.2.
+ Running the C++ Broker
+ </a></span></dt><dt><span class="section"><a href="#RASC-Mostcommonquestionsgettingqpiddrunning">1.3.
+ Most
+ common questions getting qpidd running
+ </a></span></dt><dt><span class="section"><a href="#RASC-Authentication">1.4.
+ Authentication
+ </a></span></dt><dt><span class="section"><a href="#RASC-Slightlymorecomplexconfiguration">1.5.
+ Slightly more
+ complex configuration
+ </a></span></dt><dt><span class="section"><a href="#RASC-Loadingextramodules">1.6.
+ Loading extra modules
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2494687">2.
+ Cheat Sheet for configuring Queue Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions">2.1.
+ Configuring
+ Queue Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2742008">3.
+ Cheat Sheet for configuring Exchange Options
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions">3.1.
+ Configuring Exchange Options
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2743074">4.
+ Using Broker Federation
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#UsingBrokerFederation-Introduction">4.1.
+ Introduction
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-WhatIsBrokerFederation-3F">4.2.
+ What Is
+ Broker Federation?
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-TheqpidrouteUtility">4.3.
+ The
+ qpid-route Utility
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-ExampleScenarios">4.4.
+ Example
+ Scenarios
+ </a></span></dt><dt><span class="section"><a href="#UsingBrokerFederation-AdvancedTopics">4.5.
+ Advanced
+ Topics
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2744550">5.
+ SSL
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#SSL-SSLHowto">5.1.
+ SSL How to
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2743638">6.
+ LVQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#LVQ-UnderstandingLVQ">6.1.
+ Understanding LVQ
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQsemantics-3A">6.2.
+ LVQ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-LVQNOBROWSEsemantics-3A">6.3.
+ LVQ_NO_BROWSE
+ semantics:
+ </a></span></dt><dt><span class="section"><a href="#LVQ-Examplesource">6.4.
+ LVQ Program Example
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#queue-state-replication">7.
+ Queue State Replication
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#queuestatereplication-AsynchronousReplicationofQueueState">7.1.
+ Asynchronous
+ Replication of Queue State
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2745445">8.
+ Starting a cluster
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#Startingacluster-RunningaQpiddcluster">8.1.
+ Running a
+ Qpidd cluster
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#qpid_ACL">9.
+ ACL
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ACL-v2ACLfileformatforbrokers">9.1.
+ v2 ACL file format for brokers
+ </a></span></dt><dt><span class="section"><a href="#ACL-DesignDocumentation">9.2.
+ Design Documentation
+ </a></span></dt><dt><span class="section"><a href="#ACL-v2ACLUserGuide">9.3.
+ v2 ACL User Guide
+ </a></span></dt></dl></dd></dl></div><div class="section" title="1. Running a Qpid C++ Broker"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-Running-a-Qpid-CPP-Broker"></a>1.
+ Running a Qpid C++ Broker
+ </h2></div></div></div><div class="section" title="1.1. Building the C++ Broker and Client Libraries"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-BuildingtheCppBrokerandClientLibraries"></a>1.1.
+ Building the
+ C++ Broker and Client Libraries
+ </h3></div></div></div><p>
+ The root directory for the C++ distribution is named
+ qpidc-0.4. The README file in that directory gives
+ instructions for building the broker and client libraries. In
+ most cases you will do the following:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ ./configure
+[qpidc-0.4]$ make
+</pre></div><div class="section" title="1.2. Running the C++ Broker"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-RunningtheCppBroker"></a>1.2.
+ Running the C++ Broker
+ </h3></div></div></div><p>
+ Once you have built the broker and client libraries, you can
+ start the broker from the command line:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd
+</pre><p>
+ Use the --daemon option to run the broker as a daemon
+ process:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --daemon
+</pre><p>
+ You can stop a running daemon with the --quit option:
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --quit
+</pre><p>
+ You can see all available options with the --help option
+ </p><pre class="programlisting">
+[qpidc-0.4]$ src/qpidd --help
+</pre></div><div class="section" title="1.3. Most common questions getting qpidd running"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Mostcommonquestionsgettingqpiddrunning"></a>1.3.
+ Most
+ common questions getting qpidd running
+ </h3></div></div></div><div class="section" title='1.3.1. Error when starting broker: "no data directory"'><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Errorwhenstartingbroker-3A-22nodatadirectory-22"></a>1.3.1.
+ Error
+ when starting broker: "no data directory"
+ </h4></div></div></div><p>
+ The qpidd broker requires you to set a data directory or specify
+ --no-data-dir (see help for more details). The data
+ directory is used for the journal, so it is important when
+ reliability counts. Make sure your process has write permission
+ to the data directory.
+ </p><p>
+ The default location is
+ </p><pre class="programlisting">
+/lib/var/qpidd
+</pre><p>
+ An alternate location can be set with --data-dir
+ </p></div><div class="section" title='1.3.2. Error when starting broker: "that process is locked"'><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Errorwhenstartingbroker-3A-22thatprocessislocked-22"></a>1.3.2.
+ Error
+ when starting broker: "that process is locked"
+ </h4></div></div></div><p>
+ Note that when qpidd starts it creates a lock file is data
+ directory are being used. If you have a un-controlled exit,
+ please mail
+ the trace from the core to the dev@qpid.apache.org mailing list.
+ To clear the lock run
+ </p><pre class="programlisting">
+./qpidd -q
+</pre><p>
+ It should also be noted that multiple brokers can be run on the
+ same host. To do so set alternate data directories for each qpidd
+ instance.
+ </p></div><div class="section" title="1.3.3. Using a configuration file"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Usingaconfigurationfile"></a>1.3.3.
+ Using a configuration
+ file
+ </h4></div></div></div><p>
+ Each option that can be specified on the command line can also be
+ specified in a configuration file. To see available options, use
+ --help on the command line:
+ </p><pre class="programlisting">
+./qpidd --help
+</pre><p>
+ A configuration file uses name/value pairs, one on each line. To
+ convert a command line option to a configuration file entry:
+ </p><p>
+ a.) remove the '--' from the beginning of the option.
+ b.) place a '=' between the option and the value (use
+ <span class="emphasis"><em>yes</em></span> or <span class="emphasis"><em>true</em></span> to enable options that take no
+ value when specified on the command line).
+ c.) place one option per line.
+ </p><p>
+ For instance, the --daemon option takes no value, the
+ --log-to-syslog option takes the values yes or
+ no. The following configuration file sets these two
+ options:
+ </p><pre class="programlisting">
+daemon=yes
+log-to-syslog=yes
+</pre></div><div class="section" title="1.3.4. Can I use any Language client with the C++ Broker?"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-CanIuseanyLanguageclientwiththeCppBroker-3F"></a>1.3.4.
+ Can I use
+ any Language client with the C++ Broker?
+ </h4></div></div></div><p>
+ Yes, all the clients work with the C++ broker; it is written in
+ C+<span class="emphasis"><em>, but uses the AMQP wire protocol. Any broker can be used
+ with any client that uses the same AMQP version. When running the
+ C</em></span>+ broker, it is highly recommended to run AMQP 0-10.
+ </p><p>
+ Note that JMS also works with the C++ broker.
+ </p></div></div><div class="section" title="1.4. Authentication"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Authentication"></a>1.4.
+ Authentication
+ </h3></div></div></div><div class="section" title="1.4.1. Linux"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Linux"></a>1.4.1.
+ Linux
+ </h4></div></div></div><p>
+ The PLAIN authentication is done on a username+password, which is
+ stored in the sasldb_path file. Usernames and passwords can be
+ added to the file using the command:
+ </p><pre class="programlisting">
+saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER>
+</pre><p>
+ The REALM is important and should be the same as the
+ --auth-realm
+ option to the broker. This lets the broker properly find the user
+ in
+ the sasldb file.
+ </p><p>
+ Existing user accounts may be listed with:
+ </p><pre class="programlisting">
+sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
+</pre><p>
+ NOTE: The sasldb file must be readable by the user running the
+ qpidd daemon, and should be readable only by that user.
+ </p></div><div class="section" title="1.4.2. Windows"><div class="titlepage"><div><div><h4 class="title"><a name="RASC-Windows"></a>1.4.2.
+ Windows
+ </h4></div></div></div><p>
+ On Windows, the users are authenticated against the local
+ machine. You should add the appropriate users using the standard
+ Windows tools (Control Panel->User Accounts). To run many of
+ the examples, you will need to create a user "guest" with
+ password "guest".
+ </p><p>
+ If you cannot or do not want to create new users, you can run
+ without authentication by specifying the no-auth option to the
+ broker.
+ </p></div></div><div class="section" title="1.5. Slightly more complex configuration"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Slightlymorecomplexconfiguration"></a>1.5.
+ Slightly more
+ complex configuration
+ </h3></div></div></div><p>
+ The easiest way to get a full listing of the broker's options are
+ to use the --help command, run it locally for the latest set of
+ options. These options can then be set in the conf file for
+ convenience (see above)
+ </p><pre class="programlisting">
+./qpidd --help
+
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+Module options:
+ --module-dir DIR (/usr/lib/qpidd) Load all .so modules in this directory
+ --load-module FILE Specifies additional module(s) to be loaded
+ --no-module-dir Don't load modules from module directory
+
+Broker Options:
+ --data-dir DIR (/var/lib/qpidd) Directory to contain persistent data generated by the broker
+ --no-data-dir Don't use a data directory. No persistent
+ configuration will be loaded or stored
+ -p [ --port ] PORT (5672) Tells the broker to listen on PORT
+ --worker-threads N (3) Sets the broker thread pool size
+ --max-connections N (500) Sets the maximum allowed connections
+ --connection-backlog N (10) Sets the connection backlog limit for the
+ server socket
+ --staging-threshold N (5000000) Stages messages over N bytes to disk
+ -m [ --mgmt-enable ] yes|no (1) Enable Management
+ --mgmt-pub-interval SECONDS (10) Management Publish Interval
+ --ack N (0) Send session.ack/solicit-ack at least every
+ N frames. 0 disables voluntary ack/solitict
+ -ack
+
+Daemon options:
+ -d [ --daemon ] Run as a daemon.
+ -w [ --wait ] SECONDS (10) Sets the maximum wait time to initialize the
+ daemon. If the daemon fails to initialize, prints
+ an error and returns 1
+ -c [ --check ] Prints the daemon's process ID to stdout and
+ returns 0 if the daemon is running, otherwise
+ returns 1
+ -q [ --quit ] Tells the daemon to shut down
+Logging options:
+ --log-output FILE (stderr) Send log output to FILE. FILE can be a file name
+ or one of the special values:
+ stderr, stdout, syslog
+ -t [ --trace ] Enables all logging
+ --log-enable RULE (error+) Enables logging for selected levels and component
+ s. RULE is in the form 'LEVEL+:PATTERN'
+ Levels are one of:
+ trace debug info notice warning error critical
+ For example:
+ '--log-enable warning+' logs all warning, error
+ and critical messages.
+ '--log-enable debug:framing' logs debug messages
+ from the framing namespace. This option can be
+ used multiple times
+ --log-time yes|no (1) Include time in log messages
+ --log-level yes|no (1) Include severity level in log messages
+ --log-source yes|no (0) Include source file:line in log messages
+ --log-thread yes|no (0) Include thread ID in log messages
+ --log-function yes|no (0) Include function signature in log messages
+</pre></div><div class="section" title="1.6. Loading extra modules"><div class="titlepage"><div><div><h3 class="title"><a name="RASC-Loadingextramodules"></a>1.6.
+ Loading extra modules
+ </h3></div></div></div><p>
+ By default the broker will load all the modules in the module
+ directory, however it will NOT display options for modules that
+ are not loaded. So to see the options for extra modules loaded
+ you need to load the module and then add the help command like
+ this:
+ </p><pre class="programlisting">
+./qpidd --load-module libbdbstore.so --help
+Usage: qpidd OPTIONS
+Options:
+ -h [ --help ] Displays the help message
+ -v [ --version ] Displays version information
+ --config FILE (/etc/qpidd.conf) Reads configuration from FILE
+
+
+ / .... non module options would be here ... /
+
+
+Store Options:
+ --store-directory DIR Store directory location for persistence (overrides
+ --data-dir)
+ --store-async yes|no (1) Use async persistence storage - if store supports
+ it, enables AIO O_DIRECT.
+ --store-force yes|no (0) Force changing modes of store, will delete all
+ existing data if mode is changed. Be SURE you want
+ to do this!
+ --num-jfiles N (8) Number of files in persistence journal
+ --jfile-size-pgs N (24) Size of each journal file in multiples of read
+ pages (1 read page = 64kiB)
+</pre></div></div><div class="section" title="2. Cheat Sheet for configuring Queue Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2494687"></a>2.
+ Cheat Sheet for configuring Queue Options
+ </h2></div></div></div><div class="section" title="2.1. Configuring Queue Options"><div class="titlepage"><div><div><h3 class="title"><a name="CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions"></a>2.1.
+ Configuring
+ Queue Options
+ </h3></div></div></div><p>
+ The C++ Broker M4 or later supports the following additional
+ Queue constraints.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ConfiguringQueueOptions" title="2.1. Configuring Queue Options">Section 2.1, “
+ Configuring
+ Queue Options
+ ”</a>
+ </p></li><li class="listitem"><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints" title="2.1.1. Applying Queue Sizing Constraints">Section 2.1.1, “
+ Applying Queue Sizing Constraints
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29" title="2.1.2. Changing the Queue ordering Behaviors (FIFO/LVQ)">Section 2.1.2, “
+ Changing the Queue ordering Behaviors (FIFO/LVQ)
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors" title="2.1.3. Setting additional behaviors">Section 2.1.3, “
+ Setting additional behaviors
+ ”</a>
+ </p></li><li class="listitem"><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-PersistLastNode" title="2.1.3.1. Persist Last Node">Section 2.1.3.1, “
+ Persist
+ Last Node
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-Queueeventgeneration" title="2.1.3.2. Queue event generation">Section 2.1.3.2, “
+ Queue
+ event generation
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#CheatSheetforconfiguringQueueOptions-OtherClients" title="2.1.4. Other Clients">Section 2.1.4, “
+ Other
+ Clients
+ ”</a>
+ </p></li></ul></div><p>
+ </p></li></ul></div><div class="section" title="2.1.1. Applying Queue Sizing Constraints"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"></a>2.1.1.
+ Applying Queue Sizing Constraints
+ </h4></div></div></div><p>
+ This allows to specify how to size a queue and what to do when
+ the sizing constraints have been reached. The queue size can be
+ limited by the number messages (message depth) or byte depth on
+ the queue.
+ </p><p>
+ Once the Queue meets/ exceeds these constraints the follow
+ policies can be applied
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>REJECT - Reject the published message
+ </p></li><li class="listitem"><p>FLOW_TO_DISK - Flow the messages to disk, to preserve memory
+ </p></li><li class="listitem"><p>RING - start overwriting messages in a ring based on sizing.
+ If head meets tail, advance head
+ </p></li><li class="listitem"><p>RING_STRICT - start overwriting messages in a ring based on
+ sizing. If head meets tail, AND the consumer has the tail message
+ acquired it will reject
+ </p></li></ul></div><p>
+ Examples:
+ </p><p>
+ Create a queue an auto delete queue that will support 100 000
+ bytes, and then REJECT
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setSizePolicy(REJECT,100000,0);
+
+ session.queueDeclare(arg::queue=queue, arg::autoDelete=true, arg::arguments=qo);
+</pre><p>
+ Create a queue that will support 1000 messages into a RING buffer
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setSizePolicy(RING,0,1000);
+
+ session.queueDeclare(arg::queue=queue, arg::arguments=qo);
+</pre></div><div class="section" title="2.1.2. Changing the Queue ordering Behaviors (FIFO/LVQ)"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-ChangingtheQueueorderingBehaviors-28FIFO-2FLVQ-29"></a>2.1.2.
+ Changing the Queue ordering Behaviors (FIFO/LVQ)
+ </h4></div></div></div><p>
+ The default ordering in a queue in Qpid is FIFO. However
+ additional ordering semantics can be used namely LVQ (Last Value
+ Queue). Last Value Queue is define as follows.
+ </p><p>
+ If I publish symbols RHT, IBM, JAVA, MSFT, and then publish RHT
+ before the consumer is able to consume RHT, that message will be
+ over written in the queue and the consumer will receive the last
+ published value for RHT.
+ </p><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.setOrdering(LVQ);
+
+ session.queueDeclare(arg::queue=queue, arg::arguments=qo);
+
+ .....
+ string key;
+ qo.getLVQKey(key);
+
+ ....
+ for each message, set the into application headers before transfer
+ message.getHeaders().setString(key,"RHT");
+
+</pre><p>
+ Notes:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Messages that are dequeued and the re-queued will have the
+ following exceptions. a.) if a new message has been queued with
+ the same key, the re-queue from the consumer, will combine these
+ two messages. b.) If an update happens for a message of the same
+ key, after the re-queue, it will not update the re-queued
+ message. This is done to protect a client from being able to
+ adversely manipulate the queue.
+ </p></li><li class="listitem"><p>Acquire: When a message is acquired from the queue, no matter
+ it's position, it will behave the same as a dequeue
+ </p></li><li class="listitem"><p>LVQ does not support durable messages. If the queue or
+ messages are declared durable on an LVQ, the durability will be
+ ignored.
+ </p></li></ul></div><p>
+ A fully worked <a class="xref" href="#LVQ-Examplesource" title="6.4. LVQ Program Example">Section 6.4, “
+ LVQ Program Example
+ ”</a> can be found here
+ </p></div><div class="section" title="2.1.3. Setting additional behaviors"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-Settingadditionalbehaviors"></a>2.1.3.
+ Setting additional behaviors
+ </h4></div></div></div><div class="section" title="2.1.3.1. Persist Last Node"><div class="titlepage"><div><div><h5 class="title"><a name="CheatSheetforconfiguringQueueOptions-PersistLastNode"></a>2.1.3.1.
+ Persist
+ Last Node
+ </h5></div></div></div><p>
+ This option is used in conjunction with clustering. It allows for
+ a queue configured with this option to persist transient messages
+ if the cluster fails down to the last node. If additional nodes
+ in the cluster are restored it will stop persisting transient
+ messages.
+ </p><p>
+ Note
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>if a cluster is started with only one active node, this mode
+ will not be triggered. It is only triggered the first time the
+ cluster fails down to 1 node.
+ </p></li><li class="listitem"><p>The queue MUST be configured durable
+ </p></li></ul></div><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions qo;
+ qo.clearPersistLastNode();
+
+ session.queueDeclare(arg::queue=queue, arg::durable=true, arg::arguments=qo);
+</pre></div><div class="section" title="2.1.3.2. Queue event generation"><div class="titlepage"><div><div><h5 class="title"><a name="CheatSheetforconfiguringQueueOptions-Queueeventgeneration"></a>2.1.3.2.
+ Queue
+ event generation
+ </h5></div></div></div><p>
+ This option is used to determine whether enqueue/dequeue events
+ representing changes made to queue state are generated. These
+ events can then be processed by plugins such as that used for
+ <a class="xref" href="#queue-state-replication" title="7. Queue State Replication">Section 7, “
+ Queue State Replication
+ ”</a>.
+ </p><p>
+ Example:
+ </p><pre class="programlisting">
+#include "qpid/client/QueueOptions.h"
+
+ QueueOptions options;
+ options.enableQueueEvents(1);
+ session.queueDeclare(arg::queue="my-queue", arg::arguments=options);
+</pre><p>
+ The boolean option indicates whether only enqueue events should
+ be generated. The key set by this is
+ 'qpid.queue_event_generation' and the value is and integer value
+ of 1 (to replicate only enqueue events) or 2 (to replicate both
+ enqueue and dequeue events).
+ </p></div></div><div class="section" title="2.1.4. Other Clients"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringQueueOptions-OtherClients"></a>2.1.4.
+ Other
+ Clients
+ </h4></div></div></div><p>
+ Note that these options can be set from any client. QueueOptions
+ just correctly formats the arguments passed to the QueueDeclare()
+ method.
+ </p></div></div></div><div class="section" title="3. Cheat Sheet for configuring Exchange Options"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2742008"></a>3.
+ Cheat Sheet for configuring Exchange Options
+ </h2></div></div></div><div class="section" title="3.1. Configuring Exchange Options"><div class="titlepage"><div><div><h3 class="title"><a name="CheatSheetforconfiguringExchangeOptions-ConfiguringExchangeOptions"></a>3.1.
+ Configuring Exchange Options
+ </h3></div></div></div><p>
+ The C++ Broker M4 or later supports the following additional
+ Exchange options in addition to the standard AMQP define options
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exchange Level Message sequencing
+ </p></li><li class="listitem"><p>Initial Value Exchange
+ </p></li></ul></div><p>
+ Note that these features can be used on any exchange type, that
+ has been declared with the options set.
+ </p><p>
+ It also supports an additional option to the bind operation on a
+ direct exchange
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Exclusive binding for key
+ </p></li></ul></div><div class="section" title="3.1.1. Exchange Level Message sequencing"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-ExchangeLevelMessagesequencing"></a>3.1.1.
+ Exchange Level Message sequencing
+ </h4></div></div></div><p>
+ This feature can be used to place a sequence number into each
+ message's headers, based on the order they pass through an
+ exchange. The sequencing starts at 0 and then wraps in an AMQP
+ int64 type.
+ </p><p>
+ The field name used is "qpid.msg_sequence"
+ </p><p>
+ To use this feature an exchange needs to be declared specifying
+ this option in the declare
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.msg_sequence",1);
+
+...
+ // now declare the exchange
+ session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
+</pre><p>
+ Then each message passing through that exchange will be numbers
+ in the application headers.
+ </p><pre class="programlisting">
+ unit64_t seqNo;
+ //after message transfer
+ seqNo = message.getHeaders().getAsInt64("qpid.msg_sequence");
+</pre></div><div class="section" title="3.1.2. Initial Value Exchange"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-InitialValueExchange"></a>3.1.2.
+ Initial
+ Value Exchange
+ </h4></div></div></div><p>
+ This feature caches a last message sent to an exchange. When a
+ new binding is created onto the exchange it will then attempt to
+ route this cached messaged to the queue, based on the binding.
+ This allows for topics or the creation of configurations where a
+ new consumer can receive the last message sent to the broker,
+ with matching routing.
+ </p><p>
+ To use this feature an exchange needs to be declared specifying
+ this option in the declare
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.ive",1);
+
+...
+ // now declare the exchange
+ session.exchangeDeclare(arg::exchange="direct", arg::arguments=args);
+</pre><p>
+ now use the exchange in the same way you would use any other
+ exchange.
+ </p></div><div class="section" title="3.1.3. Exclusive binding for key"><div class="titlepage"><div><div><h4 class="title"><a name="CheatSheetforconfiguringExchangeOptions-Exclusivebindingforkey"></a>3.1.3.
+ Exclusive
+ binding for key
+ </h4></div></div></div><p>
+ Direct exchanges in qpidd support a qpid.exclusive-binding option
+ on the bind operation that causes the binding specified to be the
+ only one for the given key. I.e. if there is already a binding at
+ this exchange with this key it will be atomically updated to bind
+ the new queue. This means that the binding can be changed
+ concurrently with an incoming stream of messages and each message
+ will be routed to exactly one queue.
+ </p><pre class="programlisting">
+....
+ FieldTable args;
+ args.setInt("qpid.exclusive-binding",1);
+
+ //the following will cause the only binding from amq.direct with 'my-key'
+ //to be the one to 'my-queue'; if there were any previous bindings for that
+ //key they will be removed. This is atomic w.r.t message routing through the
+ //exchange.
+ session.exchangeBind(arg::exchange="amq.direct", arg::queue="my-queue",
+ arg::bindingKey="my-key", arg::arguments=args);
+
+...
+</pre></div></div></div><div class="section" title="4. Using Broker Federation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2743074"></a>4.
+ Using Broker Federation
+ </h2></div></div></div><div class="section" title="4.1. Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="UsingBrokerFederation-Introduction"></a>4.1.
+ Introduction
+ </h3></div></div></div><p>
+ Please note: Whereas broker federation was introduced in the M3
+ milestone release, the discussion in this document is based on
+ the richer capabilities of federation in the M4 release.
+ </p></div><div class="section" title="4.2. What Is Broker Federation?"><div class="titlepage"><div><div><h3 class="title"><a name="UsingBrokerFederation-WhatIsBrokerFederation-3F"></a>4.2.
+ What Is
+ Broker Federation?
+ </h3></div></div></div><p>
+ The Qpid C++ messaging broker supports broker federation, a
+ mechanism by which large messaging networks can be built using
+ multiple brokers. Some scenarios in which federation is useful:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <span class="emphasis"><em>Connecting disparate locations across a wide area
+ network.</em></span> In this case full connectivity across the
+ enterprise can be achieved while keeping local message traffic
+ isolated to a single location.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Departmental brokers</em></span> that have a policy which
+ controls the flow of inter-departmental message traffic.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Scaling of capacity</em></span> for expensive broker operations.
+ High-function exchanges like the XML exchange can be replicated
+ to scale performance.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Co-Resident brokers</em></span> Some applications benefit from
+ having a broker co-resident with the client. This is
+ particularly true if the client produces data that must be
+ delivered reliably but connectivity to the consumer(s) is
+ non-reliable. In this case, a co-resident broker provides
+ queueing and durablilty not available in the client alone.
+ </p></li><li class="listitem"><p>
+ <span class="emphasis"><em>Bridging disjoint IP networks.</em></span> Message brokers can
+ be configured to allow message connectivity between networks
+ where there is no IP connectivity. For example, an isolated,
+ private IP network can have messaging connectivity to brokers
+ in other outside IP networks.
+ </p></li></ul></div></div><div class="section" title="4.3. The qpid-route Utility"><div class="titlepage"><div><div><h3 class="title"><a name="UsingBrokerFederation-TheqpidrouteUtility"></a>4.3.
+ The
+ qpid-route Utility
+ </h3></div></div></div><p>
+ The qpid-route command line utility is provided with the Qpid
+ broker. This utility is used to configure federated networks of
+ brokers and to view the status and topology of networks.
+ </p><p>
+ qpid-route accesses the managed brokers remotely. It does not
+ need to be invoked from the same host on which the broker is
+ running. If network connectivity permits, an entire enterprise
+ can be configured from a single location.
+ </p><p>
+ In the following sections, federation concepts will be introduced
+ and illustrated using qpid-route.
+ </p><div class="section" title="4.3.1. Links and Routes"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-LinksandRoutes"></a>4.3.1.
+ Links and
+ Routes
+ </h4></div></div></div><p>
+ Federation occurs when a <span class="emphasis"><em>link</em></span> is established between two
+ brokers and one or more <span class="emphasis"><em>routes</em></span> are created within that
+ link. A <span class="emphasis"><em>link</em></span> is a transport level connection (tcp, rdma,
+ ssl, etc.) initiated by one broker and accepted by another. The
+ initiating broker assumes the role of <span class="emphasis"><em>client</em></span> with regard
+ to the connection. The accepting broker annotates the connection
+ as being for federation but otherwise treats it as a normal
+ client connection.
+ </p><p>
+ A <span class="emphasis"><em>route</em></span> is associated with an AMQP session established
+ over the link connection. There may be multiple routes sharing
+ the same link. A route controls the flow of messages across the
+ link between brokers. Routes always consist of a session and a
+ subscription for consuming messages. Depending on the
+ configuration, a route may have a private queue on the source
+ broker with a binding to an exchange on that broker.
+ </p><p>
+ Routes are unidirectional. A single route provides for the flow
+ of messages in one direction across a link. If bidirectional
+ connectivity is required (and it almost always is), then a pair
+ of routes must be created, one for each direction of message
+ flow.
+ </p><p>
+ The qpid-route utility allows the administrator to configure and
+ manage links and routes separately. However, when a route is
+ created and a link does not already exist, qpid-route will
+ automatically create the link. It is typically not necessary to
+ create a link by itself. It is, however, useful to get a list of
+ links and their connection status from a broker:
+ </p><pre class="programlisting">
+$ qpid-route link list localhost:10001
+
+Host Port Transport Durable State Last Error
+=============================================================================
+localhost 10002 tcp N Operational
+localhost 10003 tcp N Operational
+localhost 10009 tcp N Waiting Connection refused
+</pre><p>
+ The example above shows a <span class="emphasis"><em>link list</em></span> query to the
+ broker at "localhost:10001". In the example, this broker has
+ three links to other brokers. Two are operational and the third
+ is waiting to connect because there is not currently a broker
+ listening at that address.
+ </p><div class="section" title="4.3.1.1. The Life Cycle of a Link"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-TheLifeCycleofaLink"></a>4.3.1.1.
+ The Life
+ Cycle of a Link
+ </h5></div></div></div><p>
+ When a link is created on a broker, that broker attempts to
+ establish a transport-level connection to the peer broker. If it
+ fails to connect, it retries the connection at an increasing time
+ interval. If the connection fails due to authentication failure,
+ it will not continue to retry as administrative intervention is
+ needed to fix the problem.
+ </p><p>
+ If an operational link is disconnected, the initiating broker
+ will attempt to re-establish the connection with the same
+ interval back-off.
+ </p><p>
+ The shortest retry-interval is 2 seconds and the longest is 64
+ seconds. Once enough consecutive retries have occurred that the
+ interval has grown to 64 seconds, the interval will then stay at
+ 64 seconds.
+ </p></div><div class="section" title="4.3.1.2. Durable Links and Routes"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-DurableLinksandRoutes"></a>4.3.1.2.
+ Durable
+ Links and Routes
+ </h5></div></div></div><p>
+ If, when a link or a route is created using qpid-route, the
+ --durable option is used, it shall be durable. This
+ means that its life cycle shall span restarts of the broker. If
+ the broker is shut down, when it is restarted, the link will be
+ restored and will begin establishing connectivity.
+ </p><p>
+ A non-durable route can be created for a durable link but a
+ durable route cannot be created for a non-durable link.
+ </p><pre class="programlisting">
+$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
+$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic2 --durable
+Failed: Can't create a durable route on a non-durable link
+</pre><p>
+ In the above example, a transient (non-durable) dynamic route was
+ created between localhost:10003 and localhost:10004. Because
+ there was no link in place, a new transient link was created. The
+ second command is attempting to create a durable route over the
+ same link and is rejected as illegal.
+ </p></div></div><div class="section" title="4.3.2. Dynamic Routing"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-DynamicRouting"></a>4.3.2.
+ Dynamic
+ Routing
+ </h4></div></div></div><p>
+ Dynamic routing provides the simplest configuration for a network
+ of brokers. When configuring dynamic routing, the administrator
+ need only express the logical topology of the network (i.e. which
+ pairs of brokers are connected by a unidirectional route). Queue
+ configuration and bindings are handled automatically by the
+ brokers in the network.
+ </p><p>
+ Dynamic routing uses the <span class="emphasis"><em>Distributed Exchange</em></span> concept.
+ From the client's point of view, all of the brokers in the
+ network collectively offer a single logical exchange that behaves
+ the same as a single exchange in a single broker. Each client
+ connects to its local broker and can bind its queues to the
+ distributed exchange and publish messages to the exchange.
+ </p><p>
+ When a consuming client binds a queue to the distributed
+ exchange, information about that binding is propagated to the
+ other brokers in the network to ensure that any messages matching
+ the binding will be forwarded to the client's local broker.
+ Messages published to the distributed exchange are forwarded to
+ other brokers only if there are remote consumers to receive the
+ messages. The dynamic binding protocol ensures that messages are
+ routed only to brokers with eligible consumers. This includes
+ topologies where messages must make multiple hops to reach the
+ consumer.
+ </p><p>
+ When creating a dynamic routing network, The type and name of the
+ exchange must be the same on each broker. It is <span class="emphasis"><em>strongly</em></span>
+ recommended that dynamic routes <span class="emphasis"><em>NOT</em></span> be created using the
+ standard exchanges (that is unless all messaging is intended to
+ be federated).
+ </p><p>
+ A simple, two-broker network can be configured by creating an
+ exchange on each broker then a pair of dynamic routes (one for
+ each direction of message flow):
+ </p><p>
+ Create exchanges:
+ </p><pre class="programlisting">
+$ qpid-config -a localhost:10003 add exchange topic fed.topic
+$ qpid-config -a localhost:10004 add exchange topic fed.topic
+</pre><p>
+ Create dynamic routes:
+ </p><pre class="programlisting">
+$ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
+$ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
+</pre><p>
+ Information about existing routes can be gotten by querying each
+ broker individually:
+ </p><pre class="programlisting">
+$ qpid-route route list localhost:10003
+localhost:10003 localhost:10004 fed.topic <dynamic>
+$ qpid-route route list localhost:10004
+localhost:10004 localhost:10003 fed.topic <dynamic>
+</pre><p>
+ A nicer way to view the topology is to use <span class="emphasis"><em>qpid-route route
+ map</em></span>. The argument to this command is a single broker that
+ serves as an entry point. <span class="emphasis"><em>qpid-route</em></span> will attempt to
+ recursively find all of the brokers involved in federation
+ relationships with the starting broker and map all of the routes
+ it finds.
+ </p><pre class="programlisting">
+$ qpid-route route map localhost:10003
+
+Finding Linked Brokers:
+ localhost:10003... Ok
+ localhost:10004... Ok
+
+Dynamic Routes:
+
+ Exchange fed.topic:
+ localhost:10004 <=> localhost:10003
+
+Static Routes:
+ none found
+</pre><p>
+ More extensive and realistic examples are supplied later in this
+ document.
+ </p></div><div class="section" title="4.3.3. Static Routing"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-StaticRouting"></a>4.3.3.
+ Static Routing
+ </h4></div></div></div><p>
+ Dynamic routing provides simple, efficient, and automatic
+ handling of the bindings that control routing as long as the
+ configuration keeps within a set of constraints (i.e. exchanges
+ of the same type and name, bidirectional traffic flow, etc.).
+ However, there are scenarios where it is useful for the
+ administrator to have a bit more control over the details. In
+ these cases, static routing is appropriate.
+ </p><div class="section" title="4.3.3.1. Exchange Routes"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-ExchangeRoutes"></a>4.3.3.1.
+ Exchange
+ Routes
+ </h5></div></div></div><p>
+ An exchange route is like a dynamic route except that the
+ exchange binding is statically set at creation time instead of
+ dynamically tracking changes in the network.
+ </p><p>
+ When an exchange route is created, a private queue (auto-delete,
+ exclusive) is declared on the source broker. The queue is bound
+ to the indicated exchange with the indicated key and the
+ destination broker subscribes to the queue with a destination of
+ the indicated exchange. Since only one exchange name is supplied,
+ this means that exchange routes require that the source and
+ destination exchanges have the same name.
+ </p><p>
+ Static exchange routes are added and deleted using <span class="emphasis"><em>qpid-route
+ route add</em></span> and <span class="emphasis"><em>qpid-route route del</em></span> respectively. The
+ following example creates a static exchange route with a binding
+ key of "global.#" on the default topic exchange:
+ </p><pre class="programlisting">
+$ qpid-route route add localhost:10001 localhost:10002 amq.topic global.#
+</pre><p>
+ The route can be viewed by querying the originating broker (the
+ destination in this case, see discussion of push and pull routes
+ for more on this):
+ </p><pre class="programlisting">
+$ qpid-route route list localhost:10001
+localhost:10001 localhost:10002 amq.topic global.#
+</pre><p>
+ Alternatively, the <span class="emphasis"><em>route map</em></span> feature can be used to view
+ the topology:
+ </p><pre class="programlisting">
+$ qpid-route route map localhost:10001
+
+Finding Linked Brokers:
+ localhost:10001... Ok
+ localhost:10002... Ok
+
+Dynamic Routes:
+ none found
+
+Static Routes:
+
+ localhost:10001(ex=amq.topic) <= localhost:10002(ex=amq.topic) key=global.#
+</pre><p>
+ This example causes messages delivered to the <span class="emphasis"><em>amq.topic</em></span>
+ exchange on broker <span class="emphasis"><em>localhost:10002</em></span> that have a key that
+ matches <span class="emphasis"><em>global.#</em></span> (i.e. starts with the string "global.")
+ to be delivered to the <span class="emphasis"><em>amq.topic</em></span> exchange on broker
+ <span class="emphasis"><em>localhost:10001</em></span>. This delivery will occur regardless of
+ whether there are any consumers on <span class="emphasis"><em>localhost:10001</em></span> that
+ will receive the messages.
+ </p><p>
+ Note that this is a uni-directional route. No messages will be
+ forwarded in the opposite direction unless another static route
+ is created in the other direction.
+ </p><p>
+ The following diagram illustrates the result, in terms of AMQP
+ objects, of the example static exchange route. In this diagram,
+ the exchanges, both named "amq.topic" exist prior to the creation
+ of the route. The creation of the route causes the private queue,
+ the binding, and the subscription of the queue to the destination
+ to be created.
+ </p><pre class="programlisting">
+ -------------------------------------------------+ +------------------------
+ localhost:10002 | | localhost:10001
+ | |
+ +-------------+ | | +-------------+
+ | | | | | |
+ | | global.# ---------------+ | | | |
+ | amq.topic |-----------> private queue |--------------->| amq.topic |
+ | | ---------------+ | | | |
+ | | | | | |
+ +-------------+ | | +-------------+
+ | |
+ | |
+ -------------------------------------------------+ +------------------------
+</pre></div><div class="section" title="4.3.3.2. Queue Routes"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-QueueRoutes"></a>4.3.3.2.
+ Queue Routes
+ </h5></div></div></div><p>
+ A queue route causes the destination broker to create a
+ subscription to a pre-existing, possibly shared, queue on the
+ source broker. There's no requirement that the queue be bound to
+ any particular exchange. Queue routes can be used to connect
+ exchanges of different names and/or types. They can also be used
+ to distribute or balance traffic across multiple destination
+ brokers.
+ </p><p>
+ Queue routes are created and deleted using the <span class="emphasis"><em>qpid-route
+ queue add</em></span> and <span class="emphasis"><em>qpid-route queue del</em></span> commands
+ respectively. The following example creates a static queue route
+ to a public queue called "public" that feeds the amq.fanout
+ exchange on the destination:
+ </p><p>
+ Create a queue on the source broker:
+ </p><pre class="programlisting">
+$ qpid-config -a localhost:10002 add queue public
+</pre><p>
+ Create a queue route to the new queue
+ </p><pre class="programlisting">
+$ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public
+</pre></div><div class="section" title="4.3.3.3. Pull vs. Push Routes"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-Pullvs.PushRoutes"></a>4.3.3.3.
+ Pull vs.
+ Push Routes
+ </h5></div></div></div><p>
+ When qpid-route creates or deletes a route, it establishes a
+ connection to one of the brokers involved in the route and
+ configures that broker. The configured broker then takes it upon
+ itself to contact the other broker and exchange whatever
+ information is needed to complete the setup of the route.
+ </p><p>
+ The notion of <span class="emphasis"><em>push</em></span> vs. <span class="emphasis"><em>pull</em></span> is concerned with
+ whether the configured broker is the source or the destination.
+ The normal case is the pull route, where qpid-route configures
+ the destination to pull messages from the source. A push route
+ occurs when qpid-route configures the source to push messages to
+ the destination.
+ </p><p>
+ Dynamic routes are always pull routes. Static routes are normally
+ pull routes but may be inverted by using the src-local
+ option when creating (or deleting) a route. If src-local
+ is specified, qpid-route will make its connection to the source
+ broker rather than the destination and configure the route to
+ push rather than pull.
+ </p><p>
+ Push routes are useful in applications where brokers are
+ co-resident with data sources and are configured to send data to
+ a central broker. Rather than configure the central broker for
+ each source, the sources can be configured to send to the
+ destination.
+ </p></div></div><div class="section" title="4.3.4. qpid-route Summary and Options"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-qpidrouteSummaryandOptions"></a>4.3.4.
+ qpid-route
+ Summary and Options
+ </h4></div></div></div><pre class="programlisting">
+$ qpid-route
+Usage: qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> [tag] [exclude-list]
+ qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange>
+
+ qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> [tag] [exclude-list]
+ qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key>
+ qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <exchange> <queue>
+ qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <exchange> <queue>
+ qpid-route [OPTIONS] route list [<dest-broker>]
+ qpid-route [OPTIONS] route flush [<dest-broker>]
+ qpid-route [OPTIONS] route map [<broker>]
+
+ qpid-route [OPTIONS] link add <dest-broker> <src-broker>
+ qpid-route [OPTIONS] link del <dest-broker> <src-broker>
+ qpid-route [OPTIONS] link list [<dest-broker>]
+
+Options:
+ --timeout seconds (10) Maximum time to wait for broker connection
+ -v [ --verbose ] Verbose output
+ -q [ --quiet ] Quiet output, don't print duplicate warnings
+ -d [ --durable ] Added configuration shall be durable
+ -e [ --del-empty-link ] Delete link after deleting last route on the link
+ -s [ --src-local ] Make connection to source broker (push route)
+ --ack N Acknowledge transfers over the bridge in batches of N
+ -t <transport> [ --transport <transport>]
+ Specify transport to use for links, defaults to tcp
+
+ dest-broker and src-broker are in the form: [username/password@] hostname | ip-address [:<port>]
+ ex: localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost
+</pre><p>
+ There are several transport options available for the federation
+ link:
+ </p><div class="table"><a name="id2744840"></a><p class="title"><b>Table 1.1. Transport Options for Federation</b></p><div class="table-contents"><table summary="Transport Options for Federation" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+ Transport
+ </td><td>
+ Description
+ </td></tr><tr><td>
+ tcp
+ </td><td>
+ (default) A cleartext TCP connection
+ </td></tr><tr><td>
+ ssl
+ </td><td>
+ A secure TLS/SSL over TCP connection
+ </td></tr><tr><td>
+ rdma
+ </td><td>
+ A Connection using the RDMA interface (typically for an
+ Infiniband network)
+ </td></tr></tbody></table></div></div><br class="table-break"><p>
+ The <span class="emphasis"><em>tag</em></span> and <span class="emphasis"><em>exclude-list</em></span> arguments are not
+ needed. They have been left in place for backward compatibility
+ and for advanced users who might have very unusual requirements.
+ If you're not sure if you need them, you don't. Leave them alone.
+ If you must know, please refer to "Message Loop Prevention" in
+ the advanced topics section below. The prevention of message
+ looping is now automatic and requires no user action.
+ </p><p>
+ If the link between the two sites has network latency, this can
+ be compensated for by increasing the ack frequency with --ack N
+ to achieve better batching across the link between the two sites.
+ </p></div><div class="section" title="4.3.5. Caveats, Limitations, and Things to Avoid"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-Caveats-2CLimitations-2CandThingstoAvoid"></a>4.3.5.
+ Caveats,
+ Limitations, and Things to Avoid
+ </h4></div></div></div><div class="section" title="4.3.5.1. Redundant Paths"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-RedundantPaths"></a>4.3.5.1.
+ Redundant
+ Paths
+ </h5></div></div></div><p>
+ The current implementation of federation in the M4 broker imposes
+ constraints on redundancy in the topology. If there are parallel
+ paths from a producer to a consumer, multiple copies of messages
+ may be received.
+ </p><p>
+ A future release of Qpid will solve this problem by allowing
+ redundant paths with cost metrics. This will allow the deployment
+ of networks that are tolerant of connection or broker loss.
+ </p></div><div class="section" title="4.3.5.2. Lack of Flow Control"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-LackofFlowControl"></a>4.3.5.2.
+ Lack of
+ Flow Control
+ </h5></div></div></div><p>
+ M4 broker federation uses unlimited flow control on the
+ federation sessions. Flow control back-pressure will not be
+ applied on inter-broker subscriptions.
+ </p></div><div class="section" title="4.3.5.3. Lack of Cluster Failover Support"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-LackofClusterFailoverSupport"></a>4.3.5.3.
+ Lack of
+ Cluster Failover Support
+ </h5></div></div></div><p>
+ The client functionality embedded in the broker for inter-broker
+ links does not currently support cluster fail-over. This will be
+ added in a subsequent release.
+ </p></div></div></div><div class="section" title="4.4. Example Scenarios"><div class="titlepage"><div><div><h3 class="title"><a name="UsingBrokerFederation-ExampleScenarios"></a>4.4.
+ Example
+ Scenarios
+ </h3></div></div></div><div class="section" title="4.4.1. Using QPID to bridge disjoint IP networks"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-UsingQPIDtobridgedisjointIPnetworks"></a>4.4.1.
+ Using
+ QPID to bridge disjoint IP networks
+ </h4></div></div></div><div class="section" title="4.4.1.1. Multi-tiered topology"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-Multitieredtopology"></a>4.4.1.1.
+ Multi-tiered
+ topology
+ </h5></div></div></div><pre class="programlisting">
+ +-----+
+ | 5 |
+ +-----+
+ / \
+ +-----+ +-----+
+ | 2 | | 6 |
+ +-----+ +-----+
+ / | \ | \
+ +-----+ +-----+ +-----+ +-----+ +-----+
+ | 1 | | 3 | | 4 | | 7 | | 8 |
+ +-----+ +-----+ +-----+ +-----+ +-----+
+</pre><p>
+ This topology can be configured using the following script.
+ </p><pre class="programlisting">
+##
+## Define URLs for the brokers
+##
+broker1=localhost:10001
+broker2=localhost:10002
+broker3=localhost:10003
+broker4=localhost:10004
+broker5=localhost:10005
+broker6=localhost:10006
+broker7=localhost:10007
+broker8=localhost:10008
+
+##
+## Create Topic Exchanges
+##
+qpid-config -a $broker1 add exchange topic fed.topic
+qpid-config -a $broker2 add exchange topic fed.topic
+qpid-config -a $broker3 add exchange topic fed.topic
+qpid-config -a $broker4 add exchange topic fed.topic
+qpid-config -a $broker5 add exchange topic fed.topic
+qpid-config -a $broker6 add exchange topic fed.topic
+qpid-config -a $broker7 add exchange topic fed.topic
+qpid-config -a $broker8 add exchange topic fed.topic
+
+##
+## Create Topic Routes
+##
+qpid-route dynamic add $broker1 $broker2 fed.topic
+qpid-route dynamic add $broker2 $broker1 fed.topic
+
+qpid-route dynamic add $broker3 $broker2 fed.topic
+qpid-route dynamic add $broker2 $broker3 fed.topic
+
+qpid-route dynamic add $broker4 $broker2 fed.topic
+qpid-route dynamic add $broker2 $broker4 fed.topic
+
+qpid-route dynamic add $broker2 $broker5 fed.topic
+qpid-route dynamic add $broker5 $broker2 fed.topic
+
+qpid-route dynamic add $broker5 $broker6 fed.topic
+qpid-route dynamic add $broker6 $broker5 fed.topic
+
+qpid-route dynamic add $broker6 $broker7 fed.topic
+qpid-route dynamic add $broker7 $broker6 fed.topic
+
+qpid-route dynamic add $broker6 $broker8 fed.topic
+qpid-route dynamic add $broker8 $broker6 fed.topic
+</pre></div><div class="section" title="4.4.1.2. Load-sharing across brokers"><div class="titlepage"><div><div><h5 class="title"><a name="UsingBrokerFederation-Loadsharingacrossbrokers"></a>4.4.1.2.
+ Load-sharing
+ across brokers
+ </h5></div></div></div><p></p></div></div></div><div class="section" title="4.5. Advanced Topics"><div class="titlepage"><div><div><h3 class="title"><a name="UsingBrokerFederation-AdvancedTopics"></a>4.5.
+ Advanced
+ Topics
+ </h3></div></div></div><div class="section" title="4.5.1. Federation Queue Naming"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-FederationQueueNaming"></a>4.5.1.
+ Federation
+ Queue Naming
+ </h4></div></div></div><p></p></div><div class="section" title="4.5.2. Message Loop Prevention"><div class="titlepage"><div><div><h4 class="title"><a name="UsingBrokerFederation-MessageLoopPrevention"></a>4.5.2.
+ Message
+ Loop Prevention
+ </h4></div></div></div><p></p></div></div></div><div class="section" title="5. SSL"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2744550"></a>5.
+ SSL
+ </h2></div></div></div><div class="section" title="5.1. SSL How to"><div class="titlepage"><div><div><h3 class="title"><a name="SSL-SSLHowto"></a>5.1.
+ SSL How to
+ </h3></div></div></div><div class="section" title="5.1.1. C++ broker (M4 and up)"><div class="titlepage"><div><div><h4 class="title"><a name="SSL-C-5Cbroker-28M4andup-29"></a>5.1.1.
+ C++ broker (M4 and up)
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You need to get a certificate signed by a CA, trusted by your
+ client.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>If you require client authentication, the clients certificate
+ needs to be signed by a CA trusted by the broker.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Setting up the certificates for testing.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>For testing purposes you could use the <a class="xref" href="#">???</a> to setup your certificates.
+ </p></li><li class="listitem"><p>In summary you need to create a root CA and import it to
+ the brokers certificate data base.
+ </p></li><li class="listitem"><p>Create a certificate for the broker, sign it using the
+ root CA and then import it into the brokers certificate data
+ base.
+ </p></li></ul></div><p>
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Load the acl module using --load-module or if loading more
+ than one module, copy ssl.so to the location pointed by
+ --module-dir
+
+ </p><pre class="programlisting">
+Ex if running from source. ./qpidd --load-module /libs/ssl.so
+</pre><p>
+
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Specify the password file (a plain text file with the
+ password), certificate database and the brokers certificate name
+ using the following options
+
+ </p><pre class="programlisting">
+Ex ./qpidd ... --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain
+</pre><p>
+
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>If you require client authentication you need to add
+ --ssl-require-client-authentication as a command line argument.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Please note that the default port for SSL connections is
+ 5671, unless specified by --ssl-port
+ </p></li></ul></div><p>
+ Here is an example of a broker instance that requires SSL client
+ side authenticaiton
+ </p><pre class="programlisting">
+./qpidd ./qpidd --load-module /libs/ssl.so --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain --ssl-require-client-authentication
+</pre></div><div class="section" title="5.1.2. Java Client (M4 and up)"><div class="titlepage"><div><div><h4 class="title"><a name="SSL-JavaClient-28M4andup-29"></a>5.1.2.
+ Java Client (M4 and up)
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>This guide is for connecting with the Qpid c++ broker.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Setting up the certificates for testing. In summary,
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>You need to import the trusted CA in your trust store and
+ keystore
+ </p></li><li class="listitem"><p>Generate keys for the certificate in your key store
+ </p></li><li class="listitem"><p>Create a certificate request using the generated keys
+ </p></li><li class="listitem"><p>Create a certficate using the request, signed by the
+ trusted CA.
+ </p></li><li class="listitem"><p>Import the signed certificate into your keystore.
+ </p></li></ul></div><p>
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Pass the following JVM arguments to your client.
+
+ </p><pre class="programlisting">
+-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks
+ -Djavax.net.ssl.keyStorePassword=password
+ -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks
+ -Djavax.net.ssl.trustStorePassword=password
+</pre><p>
+
+ </p></li></ul></div></div><div class="section" title="5.1.3. .Net Client (M4 and up)"><div class="titlepage"><div><div><h4 class="title"><a name="SSL-.NetClient-28M4andup-29"></a>5.1.3.
+ .Net Client (M4 and up)
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>If the Qpid broker requires client authentication then you
+ need to get a certificate signed by a CA, trusted by your client.
+ </p></li></ul></div><p>
+ Use the connectSSL instead of the standard connect method of the
+ client interface.
+ </p><p>
+ connectSSL signature is as follows:
+ </p><pre class="programlisting">
+public void connectSSL(String host, int port, String virtualHost, String username, String password, String serverName, String certPath, bool rejectUntrusted)
+</pre><p>
+ Where
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>host: Host name on which a Qpid broker is deployed
+ </p></li><li class="listitem"><p>port: Qpid broker port
+ </p></li><li class="listitem"><p>virtualHost: Qpid virtual host name
+ </p></li><li class="listitem"><p>username: User Name
+ </p></li><li class="listitem"><p>password: Password
+ </p></li><li class="listitem"><p>serverName: Name of the SSL server
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>certPath: Path to the X509 certificate to be used when the
+ broker requires client authentication
+ </p></li><li class="listitem"><p>rejectUntrusted: If true connection will not be established
+ if the broker is not trusted (the server certificate must be
+ added in your truststore)
+ </p></li></ul></div></div><div class="section" title="5.1.4. Python & Ruby Client (M4 and up)"><div class="titlepage"><div><div><h4 class="title"><a name="SSL-Python-26RubyClient-28M4andup-29"></a>5.1.4.
+ Python &
+ Ruby Client (M4 and up)
+ </h4></div></div></div><p>
+ Simply use amqps:// in the URL string as defined above
+ </p></div></div></div><div class="section" title="6. LVQ"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2743638"></a>6.
+ LVQ
+ </h2></div></div></div><div class="section" title="6.1. Understanding LVQ"><div class="titlepage"><div><div><h3 class="title"><a name="LVQ-UnderstandingLVQ"></a>6.1.
+ Understanding LVQ
+ </h3></div></div></div><p>
+ Last Value Queues are useful youUser Documentation are only
+ interested in the latest value entered into a queue. LVQ
+ semantics are typically used for things like stock symbol updates
+ when all you care about is the latest value for example.
+ </p><p>
+ Qpid C++ M4 or later supports two types of LVQ semantics:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>LVQ
+ </p></li><li class="listitem"><p>LVQ_NO_BROWSE
+ </p></li></ul></div></div><div class="section" title="6.2. LVQ semantics:"><div class="titlepage"><div><div><h3 class="title"><a name="LVQ-LVQsemantics-3A"></a>6.2.
+ LVQ semantics:
+ </h3></div></div></div><p>
+ LVQ uses a header for a key, if the key matches it replaces the
+ message in-place in the queue except
+ a.) if the message with the matching key has been acquired
+ b.) if the message with the matching key has been browsed
+ In these two cases the message is placed into the queue in FIFO,
+ if another message with the same key is received it will the
+ 'un-accessed' message with the same key will be replaced
+ </p><p>
+ These two exceptions protect the consumer from missing the last
+ update where a consumer or browser accesses a message and an
+ update comes with the same key.
+ </p><p>
+ An example
+ </p><pre class="programlisting">
+[localhost tests]$ ./lvqtest --mode create_lvq
+[localhost tests]$ ./lvqtest --mode write
+Sending Data: key1=key1.0x7fffdf3f3180
+Sending Data: key2=key2.0x7fffdf3f3180
+Sending Data: key3=key3.0x7fffdf3f3180
+Sending Data: key1=key1.0x7fffdf3f3180
+Sending Data: last=last
+[localhost tests]$ ./lvqtest --mode browse
+Receiving Data:key1.0x7fffdf3f3180
+Receiving Data:key2.0x7fffdf3f3180
+Receiving Data:key3.0x7fffdf3f3180
+Receiving Data:last
+[localhost tests]$ ./lvqtest --mode write
+Sending Data: key1=key1.0x7fffe4c7fa10
+Sending Data: key2=key2.0x7fffe4c7fa10
+Sending Data: key3=key3.0x7fffe4c7fa10
+Sending Data: key1=key1.0x7fffe4c7fa10
+Sending Data: last=last
+[localhost tests]$ ./lvqtest --mode browse
+Receiving Data:key1.0x7fffe4c7fa10
+Receiving Data:key2.0x7fffe4c7fa10
+Receiving Data:key3.0x7fffe4c7fa10
+Receiving Data:last
+[localhost tests]$ ./lvqtest --mode consume
+Receiving Data:key1.0x7fffdf3f3180
+Receiving Data:key2.0x7fffdf3f3180
+Receiving Data:key3.0x7fffdf3f3180
+Receiving Data:last
+Receiving Data:key1.0x7fffe4c7fa10
+Receiving Data:key2.0x7fffe4c7fa10
+Receiving Data:key3.0x7fffe4c7fa10
+Receiving Data:last
+</pre></div><div class="section" title="6.3. LVQ_NO_BROWSE semantics:"><div class="titlepage"><div><div><h3 class="title"><a name="LVQ-LVQNOBROWSEsemantics-3A"></a>6.3.
+ LVQ_NO_BROWSE
+ semantics:
+ </h3></div></div></div><p>
+ LVQ uses a header for a key, if the key matches it replaces the
+ message in-place in the queue except
+ a.) if the message with the matching key has been acquired
+ In these two cases the message is placed into the queue in FIFO,
+ if another message with the same key is received it will the
+ 'un-accessed' message with the same key will be replaced
+ </p><p>
+ Note, in this case browsed messaged are not invalidated, so
+ updates can be missed.
+ </p><p>
+ An example
+ </p><pre class="programlisting">
+[localhost tests]$ ./lvqtest --mode create_lvq_no_browse
+[localhost tests]$ ./lvqtest --mode write
+Sending Data: key1=key1.0x7fffce5fb390
+Sending Data: key2=key2.0x7fffce5fb390
+Sending Data: key3=key3.0x7fffce5fb390
+Sending Data: key1=key1.0x7fffce5fb390
+Sending Data: last=last
+[localhost tests]$ ./lvqtest --mode write
+Sending Data: key1=key1.0x7fff346ae440
+Sending Data: key2=key2.0x7fff346ae440
[... 3230 lines stripped ...]
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org