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 [20/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/Qpid-Book/html/ch05s02.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch05s02.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/Qpid-Book/html/ch05s02.html (added)
+++ qpid/site/docs/books/0.7/Qpid-Book/html/ch05s02.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,195 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2. Cheat Sheet for configuring Queue Options</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="prev" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="next" href="ch05s03.html" title="3. Cheat Sheet for configuring Exchange Options"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.
+ Cheat Sheet for configuring Queue Options
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch05s03.html">Next</a></td></tr></table><hr></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="id2906521"></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="ch05s02.html#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="ch05s02.html#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="ch05s02.html#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="ch05s02.html#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="ch05s02.html#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="ch05s02.html#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="ch05s02.html#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="ch05s06.html#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="ch05s07.html" 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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5.
+ Running the AMQP Messaging Broker
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
+ Cheat Sheet for configuring Exchange Options
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.7/Qpid-Book/html/ch05s03.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch05s03.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/Qpid-Book/html/ch05s03.html (added)
+++ qpid/site/docs/books/0.7/Qpid-Book/html/ch05s03.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,100 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3. Cheat Sheet for configuring Exchange Options</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="prev" href="ch05s02.html" title="2. Cheat Sheet for configuring Queue Options"><link rel="next" href="ch05s04.html" title="4. Using Broker Federation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.
+ Cheat Sheet for configuring Exchange Options
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s02.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch05s04.html">Next</a></td></tr></table><hr></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="id2990576"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Cheat Sheet for configuring Queue Options
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
+ Using Broker Federation
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.7/Qpid-Book/html/ch05s04.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch05s04.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/Qpid-Book/html/ch05s04.html (added)
+++ qpid/site/docs/books/0.7/Qpid-Book/html/ch05s04.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,550 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. Using Broker Federation</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="prev" href="ch05s03.html" title="3. Cheat Sheet for configuring Exchange Options"><link rel="next" href="ch05s05.html" title="5. SSL"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.
+ Using Broker Federation
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr></table><hr></div><div class="section" title="4. Using Broker Federation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2990780"></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="id3004210"></a><p class="title"><b>Table 5.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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.
+ Cheat Sheet for configuring Exchange Options
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5.
+ SSL
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.7/Qpid-Book/html/ch05s05.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch05s05.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/Qpid-Book/html/ch05s05.html (added)
+++ qpid/site/docs/books/0.7/Qpid-Book/html/ch05s05.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,102 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>5. SSL</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="prev" href="ch05s04.html" title="4. Using Broker Federation"><link rel="next" href="ch05s06.html" title="6. LVQ"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.
+ SSL
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s04.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch05s06.html">Next</a></td></tr></table><hr></div><div class="section" title="5. SSL"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2976527"></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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.
+ Using Broker Federation
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 6.
+ LVQ
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.7/Qpid-Book/html/ch05s06.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/Qpid-Book/html/ch05s06.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/Qpid-Book/html/ch05s06.html (added)
+++ qpid/site/docs/books/0.7/Qpid-Book/html/ch05s06.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,326 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. LVQ</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="Apache Qpid"><link rel="up" href="ch05.html" title="Chapter 5. Running the AMQP Messaging Broker"><link rel="prev" href="ch05s05.html" title="5. SSL"><link rel="next" href="ch05s07.html" title="7. Queue State Replication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6.
+ LVQ
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch05s07.html">Next</a></td></tr></table><hr></div><div class="section" title="6. LVQ"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2976890"></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
+Sending Data: key3=key3.0x7fff346ae440
+Sending Data: key1=key1.0x7fff346ae440
+Sending Data: last=last
+[localhost tests]$ ./lvqtest --mode browse
+Receiving Data:key1.0x7fff346ae440
+Receiving Data:key2.0x7fff346ae440
+Receiving Data:key3.0x7fff346ae440
+Receiving Data:last
+[localhost tests]$ ./lvqtest --mode browse
+Receiving Data:key1.0x7fff346ae440
+Receiving Data:key2.0x7fff346ae440
+Receiving Data:key3.0x7fff346ae440
+Receiving Data:last
+[localhost tests]$ ./lvqtest --mode write
+Sending Data: key1=key1.0x7fff606583e0
+Sending Data: key2=key2.0x7fff606583e0
+Sending Data: key3=key3.0x7fff606583e0
+Sending Data: key1=key1.0x7fff606583e0
+Sending Data: last=last
+[localhost tests]$ ./lvqtest --mode consume
+Receiving Data:key1.0x7fff606583e0
+Receiving Data:key2.0x7fff606583e0
+Receiving Data:key3.0x7fff606583e0
+Receiving Data:last
+[localhost tests]$
+
+</pre></div><div class="section" title="6.4. LVQ Program Example"><div class="titlepage"><div><div><h3 class="title"><a name="LVQ-Examplesource"></a>6.4.
+ LVQ Program Example
+ </h3></div></div></div><pre class="programlisting">
+
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+
+
+#include <qpid/client/AsyncSession.h>
+#include <qpid/client/Connection.h>
+#include <qpid/client/SubscriptionManager.h>
+#include <qpid/client/Session.h>
+#include <qpid/client/Message.h>
+#include <qpid/client/MessageListener.h>
+#include <qpid/client/QueueOptions.h>
+
+#include <iostream>
+
+using namespace qpid::client;
+using namespace qpid::framing;
+using namespace qpid::sys;
+using namespace qpid;
+using namespace std;
+
+
+enum Mode { CREATE_LVQ, CREATE_LVQ_NO_BROWSE, WRITE, BROWSE, CONSUME};
+const char* modeNames[] = { "create_lvq","create_lvq_no_browse","write","browse","consume" };
+
+// istream/ostream ops so Options can read/display Mode.
+istream& operator>>(istream& in, Mode& mode) {
+ string s;
+ in >> s;
+ int i = find(modeNames, modeNames+5, s) - modeNames;
+ if (i >= 5) throw Exception("Invalid mode: "+s);
+ mode = Mode(i);
+ return in;
+}
+
+ostream& operator<<(ostream& out, Mode mode) {
+ return out << modeNames[mode];
+}
+
+struct Args : public qpid::Options,
+ public qpid::client::ConnectionSettings
+{
+ bool help;
+ Mode mode;
+
+ Args() : qpid::Options("Simple latency test optins"), help(false), mode(BROWSE)
+ {
+ using namespace qpid;
+ addOptions()
+ ("help", optValue(help), "Print this usage statement")
+ ("broker,b", optValue(host, "HOST"), "Broker host to connect to")
+ ("port,p", optValue(port, "PORT"), "Broker port to connect to")
+ ("username", optValue(username, "USER"), "user name for broker log in.")
+ ("password", optValue(password, "PASSWORD"), "password for broker log in.")
+ ("mechanism", optValue(mechanism, "MECH"), "SASL mechanism to use when authenticating.")
+ ("tcp-nodelay", optValue(tcpNoDelay), "Turn on tcp-nodelay")
+ ("mode", optValue(mode, "'see below'"), "Action mode."
+ "\ncreate_lvq: create a new queue of type lvq.\n"
+ "\ncreate_lvq_no_browse: create a new queue of type lvq with no lvq on browse.\n"
+ "\nwrite: write a bunch of data & keys.\n"
+ "\nbrowse: browse the queue.\n"
+ "\nconsume: consume from the queue.\n");
+ }
+};
+
+class Listener : public MessageListener
+{
+ private:
+ Session session;
+ SubscriptionManager subscriptions;
+ std::string queue;
+ Message request;
+ QueueOptions args;
+ public:
+ Listener(Session& session);
+ void setup(bool browse);
+ void send(std::string kv);
+ void received(Message& message);
+ void browse();
+ void consume();
+};
+
+Listener::Listener(Session& s) :
+ session(s), subscriptions(s),
+ queue("LVQtester")
+{}
+
+void Listener::setup(bool browse)
+{
+ // set queue mode
+ args.setOrdering(browse?LVQ_NO_BROWSE:LVQ);
+
+ session.queueDeclare(arg::queue=queue, arg::exclusive=false, arg::autoDelete=false, arg::arguments=args);
+
+}
+
+void Listener::browse()
+{
+ subscriptions.subscribe(*this, queue, SubscriptionSettings(FlowControl::unlimited(), ACCEPT_MODE_NONE, ACQUIRE_MODE_NOT_ACQUIRED));
+ subscriptions.run();
+}
+
+void Listener::consume()
+{
+ subscriptions.subscribe(*this, queue, SubscriptionSettings(FlowControl::unlimited(), ACCEPT_MODE_NONE, ACQUIRE_MODE_PRE_ACQUIRED));
+ subscriptions.run();
+}
+
+void Listener::send(std::string kv)
+{
+ request.getDeliveryProperties().setRoutingKey(queue);
+
+ std::string key;
+ args.getLVQKey(key);
+ request.getHeaders().setString(key, kv);
+
+ std::ostringstream data;
+ data << kv;
+ if (kv != "last") data << "." << hex << this;
+ request.setData(data.str());
+
+ cout << "Sending Data: " << kv << "=" << data.str() << std::endl;
+ async(session).messageTransfer(arg::content=request);
+
+}
+
+void Listener::received(Message& response)
+{
+
+ cout << "Receiving Data:" << response.getData() << std::endl;
+/* if (response.getData() == "last"){
+ subscriptions.cancel(queue);
+ }
+*/
+}
+
+int main(int argc, char** argv)
+{
+ Args opts;
+ opts.parse(argc, argv);
+
+ if (opts.help) {
+ std::cout << opts << std::endl;
+ return 0;
+ }
+
+ Connection connection;
+ try {
+ connection.open(opts);
+ Session session = connection.newSession();
+ Listener listener(session);
+
+ switch (opts.mode)
+ {
+ case CONSUME:
+ listener.consume();
+ break;
+ case BROWSE:
+ listener.browse();
+ break;
+ case CREATE_LVQ:
+ listener.setup(false);
+ break;
+ case CREATE_LVQ_NO_BROWSE:
+ listener.setup(true);
+ break;
+ case WRITE:
+ listener.send("key1");
+ listener.send("key2");
+ listener.send("key3");
+ listener.send("key1");
+ listener.send("last");
+ break;
+ }
+ connection.close();
+ return 0;
+ } catch(const std::exception& error) {
+ std::cout << error.what() << std::endl;
+ }
+ return 1;
+}
+
+</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.
+ SSL
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7.
+ Queue State Replication
+ </td></tr></table></div></body></html>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org