Added: qpid/site/input/releases/qpid-dispatch-master/book/addressing.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/addressing.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/addressing.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/addressing.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,127 @@ + + + <div class="section" id="addressing"> +<h1>3.2. Addressing<a class="headerlink" href="#addressing" title="Permalink to this headline">.</a></h1> +<p>AMQP addresses are used to control the flow of messages across a network +of routers. Addresses are used in a number of different places in the +AMQP 1.0 protocol. They can be used in a specific message in the <cite>to</cite> +and <cite>reply-to</cite> fields of a message’s properties. They are also used +during the creation of links in the <cite>address</cite> field of a <cite>source</cite> or +a <cite>target</cite>.</p> +<p>Addresses designate various kinds of entities in a messaging network:</p> +<ul class="simple"> +<li>Endpoint processes that consume data or offer a service</li> +<li>Topics that match multiple consumers to multiple producers</li> +<li>Entities within a messaging broker: +- Queues +- Durable Topics +- Exchanges</li> +</ul> +<p>The syntax of an AMQP address is opaque as far as the router network is +concerned. A syntactical structure may be used by the administrator that +creates addresses, but the router treats them as opaque strings. Routers +consider addresses to be mobile such that any address may be directly +connected to any router in a network and may move around the topology. +In cases where messages are broadcast to or balanced across multiple +consumers, an address may be connected to multiple routers in the +network.</p> +<p>Addresses have semantics associated with them. When an address is +created in the network, it is assigned a set of semantics (and access +rules) during a process called provisioning. The semantics of an address +control how routers behave when they see the address being used.</p> +<p>Address semantics include the following considerations:</p> +<ul class="simple"> +<li><em>Routing pattern</em> - direct, multicast, balanced</li> +<li><em>Undeliverable action</em> - drop, hold and retry, redirect</li> +<li><em>Reliability</em> - N destinations, etc.</li> +</ul> +<div class="section" id="routing-patterns"> +<h2>3.2.1. Routing patterns<a class="headerlink" href="#routing-patterns" title="Permalink to this headline">.</a></h2> +<p>Routing patterns constrain the paths that a message can take across a +network.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="17%" /> +<col width="83%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Pattern</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><em>Direct</em></td> +<td>Direct routing allows for only one consumer to use an address at a +time. Messages (or links) follow the lowest cost path across the network +from the sender to the one receiver.</td> +</tr> +<tr class="row-odd"><td><em>Multicast</em></td> +<td>Multicast routing allows multiple consumers to use the same address at +the same time. Messages are routed such that each consumer receives a +copy of the message.</td> +</tr> +<tr class="row-even"><td><em>Balanced</em></td> +<td>Balanced routing also allows multiple consumers to use the same +address. In this case, messages are routed to exactly one of the +consumers, and the network attempts to balance the traffic load across +the set of consumers using the same address.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="routing-mechanisms"> +<h2>3.2.2. Routing mechanisms<a class="headerlink" href="#routing-mechanisms" title="Permalink to this headline">.</a></h2> +<p>The fact that addresses can be used in different ways suggests that +message routing can be accomplished in different ways. Before going into +the specifics of the different routing mechanisms, it would be good to +first define what is meant by the term <em>routing</em>:</p> +<blockquote> +<div>In a network built of multiple routers connected by connections +(i.e., nodes and edges in a graph), <em>routing</em> determines which +connection to use to send a message directly to its destination or +one step closer to its destination.</div></blockquote> +<p>Each router serves as the terminus of a collection of incoming and +outgoing links. The links either connect directly to endpoints that +produce and consume messages, or they connect to other routers in the +network along previously established connections.</p> +<div class="section" id="message-routing"> +<h3>3.2.2.1. Message routing<a class="headerlink" href="#message-routing" title="Permalink to this headline">.</a></h3> +<p>Message routing occurs upon delivery of a message and is done based on +the address in the message’s <cite>to</cite> field.</p> +<p>When a delivery arrives on an incoming link, the router extracts the +address from the delivered message’s <cite>to</cite> field and looks the address +up in its routing table. The lookup results in zero or more outgoing +links onto which the message shall be resent.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="19%" /> +<col width="81%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Delivery</em></th> +<th class="head"><em>Handling</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><em>pre-settled</em></td> +<td>If the arriving delivery is pre-settled (i.e., fire and forget), the +incoming delivery shall be settled by the router, and the outgoing +deliveries shall also be pre-settled. In other words, the pre-settled +nature of the message delivery is propagated across the network to the +message’s destination.</td> +</tr> +<tr class="row-odd"><td><em>unsettled</em></td> +<td>Unsettled delivery is also propagated across the network. Because +unsettled delivery records cannot be discarded, the router tracks the +incoming deliveries and keeps the association of the incoming +deliveries to the resulting outgoing deliveries. This kept association +allows the router to continue to propagate changes in delivery state +(settlement and disposition) back and forth along the path which the +message traveled.</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +
Added: qpid/site/input/releases/qpid-dispatch-master/book/amqp-mapping.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/amqp-mapping.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/amqp-mapping.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/amqp-mapping.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,205 @@ + + + <div class="section" id="amqp-mapping"> +<h1>3.3. AMQP Mapping<a class="headerlink" href="#amqp-mapping" title="Permalink to this headline">.</a></h1> +<p>Dispatch Router is an AMQP router and as such, it provides extensions, +code-points, and semantics for routing over AMQP. This page documents the +details of Dispatch Router’s use of AMQP.</p> +<div class="section" id="message-annotations"> +<h2>3.3.1. Message Annotations<a class="headerlink" href="#message-annotations" title="Permalink to this headline">.</a></h2> +<p>The following Message Annotation fields are defined by Dispatch Router:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="22%" /> +<col width="19%" /> +<col width="59%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Field</em></th> +<th class="head"><em>Type</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td>x-opt-qd.ingress</td> +<td>string</td> +<td>The identity of the ingress router for a message-routed +message. The ingress router is the first router +encountered by a transiting message. The router will, +if this field is present, leave it unaltered. If the +field is not present, the router shall insert the field +with its own identity.</td> +</tr> +<tr class="row-odd"><td>x-opt-qd.trace</td> +<td>list of string</td> +<td>The list of routers through which this message-routed +message has transited. If this field is not present, +the router shall do nothing. If the field is present, +the router shall append its own identity to the end of +the list.</td> +</tr> +<tr class="row-even"><td>x-opt-qd.to</td> +<td>string</td> +<td>To-Override for message-routed messages. If this field +is present, the address in this field shall be used for +routing in lieu of the <em>to</em> field in the message +properties. A router may append, remove, or modify this +annotation field depending on the policy in place for +routing the message.</td> +</tr> +<tr class="row-odd"><td>x-opt-qd.class</td> +<td>string</td> +<td>Message class. This is used to allow the router to +provide separate paths for different classes of +traffic.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="source-target-capabilities"> +<h2>3.3.2. Source/Target Capabilities<a class="headerlink" href="#source-target-capabilities" title="Permalink to this headline">.</a></h2> +<p>The following Capability values are used in Sources and Targets.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="17%" /> +<col width="83%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Capability</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td>qd.router</td> +<td>This capability is added to sources and targets that are used for +inter-router message exchange.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="dynamic-node-properties"> +<h2>3.3.3. Dynamic-Node-Properties<a class="headerlink" href="#dynamic-node-properties" title="Permalink to this headline">.</a></h2> +<p>The following dynamic-node-properties are used by Dispatch in Sources.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="22%" /> +<col width="78%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Property</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td>x-opt-qd.address</td> +<td>The node address describing the destination desired for a dynamic +source. If this is absent, the router will terminate any dynamic +receivers. If this address is present, the router will use the address +to route the dynamic link attach to the proper destination container.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="addresses-and-address-formats"> +<h2>3.3.4. Addresses and Address Formats<a class="headerlink" href="#addresses-and-address-formats" title="Permalink to this headline">.</a></h2> +<p>The following AMQP addresses and address patterns are used within +Dispatch Router.</p> +<div class="section" id="address-patterns"> +<h3>3.3.4.1. Address Patterns<a class="headerlink" href="#address-patterns" title="Permalink to this headline">.</a></h3> +<table border="1" class="docutils"> +<colgroup> +<col width="37%" /> +<col width="63%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Pattern</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><cite>_local/<addr></cite></td> +<td>An address that references a locally attached +endpoint. Messages using this address pattern shall not +be routed over more than one link.</td> +</tr> +<tr class="row-odd"><td><cite>_topo/<area>/<router>/<addr></cite></td> +<td>An address that references an endpoint attached to a +specific router node in the network topology. Messages +with addresses that follow this pattern shall be routed +along the shortest path to the specified router. Note +that addresses of this form are a-priori routable in +that the address itself contains enough information to +route the message to its destination.</td> +</tr> +<tr class="row-even"><td><cite><addr></cite></td> +<td>A mobile address. An address of this format represents +an endpoint or a set of distinct endpoints that are +attached to the network in arbitrary locations. It is +the responsibility of the router network to determine +which router nodes are valid destinations for mobile +addresses.</td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="supported-addresses"> +<h3>3.3.4.2. Supported Addresses<a class="headerlink" href="#supported-addresses" title="Permalink to this headline">.</a></h3> +<table border="1" class="docutils"> +<colgroup> +<col width="33%" /> +<col width="67%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Address</em></th> +<th class="head"><em>Description</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><cite>$management</cite></td> +<td>The management agent on the attached router/container. This +address would be used by an endpoint that is a management +client/console/tool wishing to access management data from +the attached container.</td> +</tr> +<tr class="row-odd"><td><cite>_topo/0/Router.E/agent</cite></td> +<td>The management agent at Router.E in area 0. This address +would be used by a management client wishing to access +management data from a specific container that is reachable +within the network.</td> +</tr> +<tr class="row-even"><td><cite>_local/qdhello</cite></td> +<td>The router entity in each of the connected routers. This +address is used to communicate with neighbor routers and is +exclusively for the HELLO discovery protocol.</td> +</tr> +<tr class="row-odd"><td><cite>_local/qdrouter</cite></td> +<td>The router entity in each of the connected routers. This +address is used by a router to communicate with other +routers in the network.</td> +</tr> +<tr class="row-even"><td><cite>_topo/0/Router.E/qdrouter</cite></td> +<td>The router entity at the specifically indicated router. This +address form is used by a router to communicate with a +specific router that may or may not be a neighbor.</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" id="implementation-of-the-amqp-management-specification"> +<h2>3.3.5. Implementation of the AMQP Management Specification<a class="headerlink" href="#implementation-of-the-amqp-management-specification" title="Permalink to this headline">.</a></h2> +<p>Qpid Dispatch is manageable remotely via AMQP. It is compliant with the +emerging AMQP Management specification (draft 9).</p> +<p>Differences from the specification:</p> +<ul class="simple"> +<li>The <cite>name</cite> attribute is not required when an entity is created. If +not supplied it will be set to the same value as the system-generated +“identity” attribute. Otherwise it is treated as per the standard.</li> +<li>The <cite>REGISTER</cite> and <cite>DEREGISTER</cite> operations are not implemented. The router +automatically discovers peer routers via the router network and makes +their management addresses available via the standard GET-MGMT-NODES +operation.</li> +</ul> +</div> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/basic_usage.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/basic_usage.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/basic_usage.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/basic_usage.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,158 @@ + + + <div class="section" id="basic-usage-and-examples"> +<h1>2.3. Basic Usage and Examples<a class="headerlink" href="#basic-usage-and-examples" title="Permalink to this headline">.</a></h1> +<div class="section" id="standalone-and-interior-modes"> +<h2>2.3.1. Standalone and Interior Modes<a class="headerlink" href="#standalone-and-interior-modes" title="Permalink to this headline">.</a></h2> +<p>The router can operate stand-alone or as a node in a network of routers. +The mode is configured in the <em>router</em> section of the configuration +file. In stand-alone mode, the router does not attempt to collaborate +with any other routers and only routes messages among directly connected +endpoints.</p> +<p>If your router is running in stand-alone mode, <em>qdstat -a</em> will look +like the following:</p> +<div class="highlight-python"><div class="highlight"><pre>$ qdstat -a +Router Addresses + class address phase in-proc local remote in out thru to-proc from-proc + =========================================================================================== + local $management Y 0 0 0 0 0 0 0 + mobile $management 0 Y 0 0 1 0 0 1 0 + local temp.4Q3i01lWbs 1 0 0 0 0 0 0 +</pre></div> +</div> +<p>Note that there are two known addresses. <em>$management</em> is the address of +the router’s embedded management agent. <em>temp.4Q3i01lWbs</em> is the temporary +reply-to address of the <em>qdstat</em> client making requests to the agent.</p> +<p>If you change the mode to interior and restart the processs, the same +command will yield additional addresses which are used for +inter-router communication:</p> +<div class="highlight-python"><div class="highlight"><pre>$ qdstat -a +Router Addresses + class address phase in-proc local remote in out thru to-proc from-proc + =========================================================================================== + local $management Y 0 0 0 0 0 0 0 + mobile $management 0 Y 0 0 1 0 0 1 0 + local qdhello Y 0 0 0 0 0 0 3 + local qdrouter Y 0 0 0 0 0 0 1 + local qdrouter.ma Y 0 0 0 0 0 0 0 + local temp.2ot2AWsnYz 1 0 0 0 0 0 0 +</pre></div> +</div> +</div> +<div class="section" id="mobile-subscribers"> +<h2>2.3.2. Mobile Subscribers<a class="headerlink" href="#mobile-subscribers" title="Permalink to this headline">.</a></h2> +<p>The term “mobile subscriber” simply refers to the fact that a client may +connect to the router and subscribe to an address to receive messages +sent to that address. No matter where in the network the subscriber +attaches, the messages will be routed to the appropriate destination.</p> +<p>To illustrate a subscription on a stand-alone router, you can use the +examples that are provided with Qpid Proton. Using the <em>simple_recv.py</em> example +receiver:</p> +<div class="highlight-python"><div class="highlight"><pre>$ python ./simple_recv.py -a 127.0.0.1/my-address +</pre></div> +</div> +<p>This command creates a receiving link subscribed to the specified +address. To verify the subscription:</p> +<div class="highlight-python"><div class="highlight"><pre>$ qdstat -a +Router Addresses + class address phase in-proc local remote in out thru to-proc from-proc + =========================================================================================== + local $management Y 0 0 0 0 0 0 0 + mobile $management 0 Y 0 0 1 0 0 1 0 + mobile my-address 0 1 0 0 0 0 0 0 + local temp.JAgKj1+iB8 1 0 0 0 0 0 0 +</pre></div> +</div> +<p>You can then, in a separate command window, run a sender to produce +messages to that address:</p> +<div class="highlight-python"><div class="highlight"><pre>$ python ./simple_send.py -a 127.0.0.1/my-address +</pre></div> +</div> +</div> +<div class="section" id="dynamic-reply-to"> +<h2>2.3.3. Dynamic Reply-To<a class="headerlink" href="#dynamic-reply-to" title="Permalink to this headline">.</a></h2> +<p>Dynamic reply-to can be used to obtain a reply-to address that routes +back to a client’s receiving link regardless of how many hops it has to +take to get there. To illustrate this feature, see below a simple +program (written in C++ against the qpid::messaging API) that queries +the management agent of the attached router for a list of other known +routers’ management addresses.</p> +<div class="highlight-python"><div class="highlight"><pre>#include <qpid/messaging/Address.h> +#include <qpid/messaging/Connection.h> +#include <qpid/messaging/Message.h> +#include <qpid/messaging/Receiver.h> +#include <qpid/messaging/Sender.h> +#include <qpid/messaging/Session.h> + +using namespace qpid::messaging; +using namespace qpid::types; + +using std::stringstream; +using std::string; + +int main() { + const char* url = "amqp:tcp:127.0.0.1:5672"; + std::string connectionOptions = "{protocol:amqp1.0}"; + + Connection connection(url, connectionOptions); + connection.open(); + Session session = connection.createSession(); + Sender sender = session.createSender("mgmt"); + + // create reply receiver and get the reply-to address + Receiver receiver = session.createReceiver("#"); + Address responseAddress = receiver.getAddress(); + + Message request; + request.setReplyTo(responseAddress); + request.setProperty("x-amqp-to", "amqp:/_local/$management"); + request.setProperty("operation", "DISCOVER-MGMT-NODES"); + request.setProperty("type", "org.amqp.management"); + request.setProperty("name, "self"); + + sender.send(request); + Message response = receiver.fetch(); + Variant content(response.getContentObject()); + std::cout << "Response: " << content << std::endl << std::endl; + + connection.close(); +} +</pre></div> +</div> +<p>The equivalent program written in Python against the Proton Messenger +API:</p> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">proton</span> <span class="kn">import</span> <span class="n">Messenger</span><span class="p">,</span> <span class="n">Message</span> + +<span class="k">def</span> <span class="nf">main</span><span class="p">():</span> + <span class="n">host</span> <span class="o">=</span> <span class="s">"0.0.0.0:5672"</span> + + <span class="n">messenger</span> <span class="o">=</span> <span class="n">Messenger</span><span class="p">()</span> + <span class="n">messenger</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> + <span class="n">messenger</span><span class="o">.</span><span class="n">route</span><span class="p">(</span><span class="s">"amqp:/*"</span><span class="p">,</span> <span class="s">"amqp://</span><span class="si">%s</span><span class="s">/$1"</span> <span class="o">%</span> <span class="n">host</span><span class="p">)</span> + <span class="n">reply_subscription</span> <span class="o">=</span> <span class="n">messenger</span><span class="o">.</span><span class="n">subscribe</span><span class="p">(</span><span class="s">"amqp:/#"</span><span class="p">)</span> + <span class="n">reply_address</span> <span class="o">=</span> <span class="n">reply_subscription</span><span class="o">.</span><span class="n">address</span> + + <span class="n">request</span> <span class="o">=</span> <span class="n">Message</span><span class="p">()</span> + <span class="n">response</span> <span class="o">=</span> <span class="n">Message</span><span class="p">()</span> + + <span class="n">request</span><span class="o">.</span><span class="n">address</span> <span class="o">=</span> <span class="s">"amqp:/_local/$management"</span> + <span class="n">request</span><span class="o">.</span><span class="n">reply_to</span> <span class="o">=</span> <span class="n">reply_address</span> + <span class="n">request</span><span class="o">.</span><span class="n">properties</span> <span class="o">=</span> <span class="p">{</span><span class="s">u'operation'</span> <span class="p">:</span> <span class="s">u'DISCOVER-MGMT-NODES'</span><span class="p">,</span> + <span class="s">u'type'</span> <span class="p">:</span> <span class="s">u'org.amqp.management'</span><span class="p">,</span> + <span class="s">u'name'</span> <span class="p">:</span> <span class="s">u'self'</span><span class="p">}</span> + + <span class="n">messenger</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">request</span><span class="p">)</span> + <span class="n">messenger</span><span class="o">.</span><span class="n">send</span><span class="p">()</span> + <span class="n">messenger</span><span class="o">.</span><span class="n">recv</span><span class="p">()</span> + <span class="n">messenger</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">response</span><span class="p">)</span> + + <span class="k">print</span> <span class="s">"Response: </span><span class="si">%r</span><span class="s">"</span> <span class="o">%</span> <span class="n">response</span><span class="o">.</span><span class="n">body</span> + + <span class="n">messenger</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> + +<span class="n">main</span><span class="p">()</span> +</pre></div> +</div> +</div> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/book.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/book.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/book.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/book.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,58 @@ + + + <div class="section" id="qpid-dispatch-router-book"> +<h1>Qpid Dispatch Router Book<a class="headerlink" href="#qpid-dispatch-router-book" title="Permalink to this headline">.</a></h1> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="introduction.html">1. Introduction</a><ul> +<li class="toctree-l2"><a class="reference internal" href="introduction.html#overview">1.1. Overview</a></li> +<li class="toctree-l2"><a class="reference internal" href="introduction.html#benefits">1.2. Benefits</a></li> +<li class="toctree-l2"><a class="reference internal" href="introduction.html#features">1.3. Features</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="using.html">2. Using Qpid Dispatch</a><ul> +<li class="toctree-l2"><a class="reference internal" href="default_config.html">2.1. Configuration</a></li> +<li class="toctree-l2"><a class="reference internal" href="tools.html">2.2. Tools</a><ul> +<li class="toctree-l3"><a class="reference internal" href="tools.html#qdstat">2.2.1. qdstat</a></li> +<li class="toctree-l3"><a class="reference internal" href="tools.html#qdmanage">2.2.2. qdmanage</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="basic_usage.html">2.3. Basic Usage and Examples</a><ul> +<li class="toctree-l3"><a class="reference internal" href="basic_usage.html#standalone-and-interior-modes">2.3.1. Standalone and Interior Modes</a></li> +<li class="toctree-l3"><a class="reference internal" href="basic_usage.html#mobile-subscribers">2.3.2. Mobile Subscribers</a></li> +<li class="toctree-l3"><a class="reference internal" href="basic_usage.html#dynamic-reply-to">2.3.3. Dynamic Reply-To</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="link_routing.html">2.4. Link Routing</a><ul> +<li class="toctree-l3"><a class="reference internal" href="link_routing.html#configuration">2.4.1. Configuration</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="technical_details.html">3. Technical Details and Specifications</a><ul> +<li class="toctree-l2"><a class="reference internal" href="client_compatibility.html">3.1. Client Compatibility</a></li> +<li class="toctree-l2"><a class="reference internal" href="addressing.html">3.2. Addressing</a><ul> +<li class="toctree-l3"><a class="reference internal" href="addressing.html#routing-patterns">3.2.1. Routing patterns</a></li> +<li class="toctree-l3"><a class="reference internal" href="addressing.html#routing-mechanisms">3.2.2. Routing mechanisms</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="amqp-mapping.html">3.3. AMQP Mapping</a><ul> +<li class="toctree-l3"><a class="reference internal" href="amqp-mapping.html#message-annotations">3.3.1. Message Annotations</a></li> +<li class="toctree-l3"><a class="reference internal" href="amqp-mapping.html#source-target-capabilities">3.3.2. Source/Target Capabilities</a></li> +<li class="toctree-l3"><a class="reference internal" href="amqp-mapping.html#dynamic-node-properties">3.3.3. Dynamic-Node-Properties</a></li> +<li class="toctree-l3"><a class="reference internal" href="amqp-mapping.html#addresses-and-address-formats">3.3.4. Addresses and Address Formats</a></li> +<li class="toctree-l3"><a class="reference internal" href="amqp-mapping.html#implementation-of-the-amqp-management-specification">3.3.5. Implementation of the AMQP Management Specification</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="schema.html">3.4. Management Schema</a><ul> +<li class="toctree-l3"><a class="reference internal" href="schema.html#configuration-entities">3.4.1. Configuration Entities</a></li> +<li class="toctree-l3"><a class="reference internal" href="schema.html#operational-entities">3.4.2. Operational Entities</a></li> +<li class="toctree-l3"><a class="reference internal" href="schema.html#management-operations">3.4.3. Management Operations</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</div> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/client_compatibility.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/client_compatibility.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/client_compatibility.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/client_compatibility.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,33 @@ + + + <div class="section" id="client-compatibility"> +<h1>3.1. Client Compatibility<a class="headerlink" href="#client-compatibility" title="Permalink to this headline">.</a></h1> +<p>Dispatch Router should, in theory, work with any client that is +compatible with AMQP 1.0. The following clients have been tested:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="20%" /> +<col width="80%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head"><em>Client</em></th> +<th class="head"><em>Notes</em></th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td>qpid::messaging</td> +<td>The Qpid messaging clients work with Dispatch Router as long as +they are configured to use the 1.0 version of the protocol. To +enable AMQP 1.0 in the C++ client, use the {protocol:amqp1.0} +connection option.</td> +</tr> +<tr class="row-odd"><td>Proton Reactor</td> +<td>The Proton Reactor API is compatible with Dispatch Router.</td> +</tr> +<tr class="row-even"><td>Proton Messenger</td> +<td>Messenger works with Dispatch Router.</td> +</tr> +</tbody> +</table> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/default_config.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/default_config.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/default_config.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/default_config.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,16 @@ + + + <div class="section" id="configuration"> +<h1>2.1. Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">.</a></h1> +<p>The default configuration file is installed in +<cite>install-prefix</cite>/etc/qpid/qdrouterd.conf. This configuration file will +cause the router to run in standalone mode, listening on the standard +AMQP port (5672). Dispatch Router looks for the configuration file in +the installed location by default. If you wish to use a different path, +the “-c” command line option will instruct Dispatch Router as to which +configuration to load.</p> +<p>To run the router, invoke the executable: qdrouterd [-c my-config-file]</p> +<p>For more details of the configuration file see the <cite>qdrouterd.conf(5)</cite> +man page.</p> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/introduction.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/introduction.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/introduction.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/introduction.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,98 @@ + + + <div class="section" id="introduction"> +<h1>1. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">.</a></h1> +<div class="section" id="overview"> +<h2>1.1. Overview<a class="headerlink" href="#overview" title="Permalink to this headline">.</a></h2> +<p>The Dispatch router is an AMQP message message router that provides +advanced interconnect capabilities. It allows flexible routing of +messages between any AMQP-enabled endpoints, whether they be clients, +servers, brokers or any other entity that can send or receive standard +AMQP messages.</p> +<p>A messaging client can make a single AMQP connection into a messaging +bus built of Dispatch routers and, over that connection, exchange +messages with one or more message brokers, and at the same time exchange +messages directly with other endpoints without involving a broker at +all.</p> +<p>The router is an intermediary for messages but it is <em>not</em> a broker. It +does not <em>take responsibility for</em> messages. It will, however, propagate +settlement and disposition across a network such that delivery +guarantees are met. In other words: the router network will deliver the +message, possibly via several intermediate routers, <em>and</em> it will route +the acknowledgement of that message by the ultimate receiver back across +the same path. This means that <em>responsibility</em> for the message is +transfered from the original sender to the ultimate receiver <em>as if they +were directly connected</em>. However this is done via a flexible network +that allows highly configurable routing of the message transparent to +both sender and receiver.</p> +<p>There are some patterns where this enables “brokerless messaging” +approaches that are preferable to brokered approaches. In other cases a +broker is essential (in particular where you need the separation of +responsibility and/or the buffering provided by store-and-forward) but a +dispatch network can still be useful to tie brokers and clients together +into patterns that are difficult with a single broker.</p> +<p>For a “brokerless” example, consider the common brokered implementation +of the request-response pattern, a client puts a request on a queue and +then waits for a reply on another queue. In this case the broker can be +a hindrance - the client may want to know immediatly if there is nobody +to serve the request, but typically it can only wait for a timeout to +discover this. With a dispatch network, the client can be informed +immediately if its message cannot be delivered because nobody is +listening. When the client receives acknowledgement of the request it +knows not just that it is sitting on a queue, but that it has actually +been received by the server.</p> +<p>For an exampe of using dispatch to enhance the use of brokers, consider +using an array of brokers to implement a scalable distributed work +queue. A dispatch network can make this appear as a single queue, with +senders publishing to a single address and receivers subscribing to a +single address. The dispatch network can distribute work to any broker +in the array and collect work from any broker for any receiver. Brokers +can be shut down or added without affecting clients. This elegantly +solves the common difficulty of “stuck messages” when implementing this +pattern with brokers alone. If a receiver is connected to a broker that +has no messages, but there are messages on another broker, you have to +somehow transfer them or leave them “stuck”. With a dispatch network, +<em>all</em> the receivers are connected to <em>all</em> the brokers. If there is a +message anywhere it can be delivered to any receiver.</p> +<p>The router is meant to be deployed in topologies of multiple routers, +preferably with redundant paths. It uses link-state routing protocols +and algorithms (similar to OSPF or IS-IS from the networking world) to +calculate the best path from every point to every other point and to +recover quickly from failures. It does not need to use clustering for +high availability; rather, it relies on redundant paths to provide +continued connectivity in the face of system or network failure. Because +it never takes responsibility for messages it is effectively stateless. +Messages not delivered to their final destination will not be +acknowledged to the sender and therefore the sender can re-send such +messages if it is disconnected from the network.</p> +</div> +<div class="section" id="benefits"> +<h2>1.2. Benefits<a class="headerlink" href="#benefits" title="Permalink to this headline">.</a></h2> +<p>Simplifies connectivity</p> +<ul class="simple"> +<li>An endpoint can do all of its messaging through a single transport connection</li> +<li>Avoid opening holes in firewalls for incoming connections</li> +</ul> +<p>Provides messaging connectivity where there is no TCP/IP connectivity</p> +<ul class="simple"> +<li>A server or broker can be in a private IP network (behind a NAT firewall) and be accessible by messaging endpoints in other networks (learn more).</li> +</ul> +<p>Simplifies reliability</p> +<ul class="simple"> +<li>Reliability and availability are provided using redundant topology, not server clustering</li> +<li>Reliable end-to-end messaging without persistent stores</li> +<li>Use a message broker only when you need store-and-forward semantics</li> +</ul> +</div> +<div class="section" id="features"> +<h2>1.3. Features<a class="headerlink" href="#features" title="Permalink to this headline">.</a></h2> +<ul class="simple"> +<li>Can be deployed stand-alone or in a network of routers +- Supports arbitrary network topology - no restrictions on redundancy +- Automatic route computation - adjusts quickly to changes in topology</li> +<li>Provides remote access to brokers or other AMQP servers</li> +<li>Security</li> +</ul> +</div> +</div> + Added: qpid/site/input/releases/qpid-dispatch-master/book/link_routing.html.in URL: http://svn.apache.org/viewvc/qpid/site/input/releases/qpid-dispatch-master/book/link_routing.html.in?rev=1705904&view=auto ============================================================================== --- qpid/site/input/releases/qpid-dispatch-master/book/link_routing.html.in (added) +++ qpid/site/input/releases/qpid-dispatch-master/book/link_routing.html.in Tue Sep 29 18:03:12 2015 @@ -0,0 +1,119 @@ + + + <div class="section" id="link-routing"> +<h1>2.4. Link Routing<a class="headerlink" href="#link-routing" title="Permalink to this headline">.</a></h1> +<p>This feature was introduced in Qpid Dispatch 0.4.</p> +<p>Link-routing is an alternative strategy for routing messages across a +network of routers. With the existing message-routing strategy, each +router makes a routing decision on a per-message basis when the +message is delivered. Link-routing is different because it makes +routing decisions when link-attach frames arrive. A link is +effectively chained across the network of routers from the +establishing node to the destination node. Once the link is +established, the transfer of message deliveries, flow frames, and +dispositions is performed across the routed link.</p> +<p>The main benefit to link-routing is that endpoints can use the full link +protocol to interact with other endpoints in far-flung parts of the +network. For example, a client can establish a receiver across the +network to a queue on a remote broker and use link credit to control +the flow of messages from the broker.</p> +<p>Why would one want to do this? One reason is to provide client +isolation. A network like the following can be deployed:</p> +<div class="highlight-python"><div class="highlight"><pre> Public Network + +-----------------+ + | +-----+ | + | B1 | Rp | | + | +/--\-+ | + | / \ | + | / \ | + +----/--------\---+ + / \ + / \ + / \ + Private Net A / \ Private Net B ++--------------/--+ +---\-------------+ +| +---/-+ | | +--\--+ | +| B2 | Ra | | | | Rb | C1 | +| +-----+ | | +-----+ | +| | | | +| | | | ++-----------------+ +-----------------+ +</pre></div> +</div> +<p>The clients in Private Net B can be constrained (by firewall policy) +to only connect to the Router in their own network. Using +link-routing, these clients can access queues, topics, and other AMQP +services that are in the Public Network or even in Private Net A.</p> +<p>For example, The router Ra can be configured to expose queues in +broker B2 to the network. Client C1 can then establish a connection +to Rb, the local router, open a subscribing link to “b2.event-queue”, +and receive messages stored on that queue in broker B2.</p> +<p>C1 is unable to create a TCP/IP connection to B1 because of its +isolation (and because B2 is itself in a private network). However, +with link routing, C1 can interact with B2 using the AMQP link +protocol.</p> +<p>Note that in this case, neither C1 nor B2 have been modified in any +way and neither need be aware of the fact that there is a +message-router network between them.</p> +<div class="section" id="configuration"> +<h2>2.4.1. Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">.</a></h2> +<p>Starting with the configured topology shown above, how is link-routing +configured to support the example described above?</p> +<p>First, router Ra needs to be told how to make a connection to the +broker B2:</p> +<div class="highlight-python"><div class="highlight"><pre>connector { + name: broker + role: on-demand + addr: <B2-url> + port: <B2-port> + sasl-mechanisms: ANONYMOUS +} +</pre></div> +</div> +<p>This <em>on-demand</em> connector tells the router how to connect to an +external AMQP container when it is needed. The name “broker” will be +used later to refer to this connection.</p> +<p>Now, the router must be configured to route certain addresses to B2:</p> +<div class="highlight-python"><div class="highlight"><pre>linkRoutePattern { + prefix: b2 + connector: broker +} +</pre></div> +</div> +<p>The linkRoutePattern tells router Ra that any sender or receiver that +is attached with a target or source (respectively) whos address begins +with “b2”, should be routed to the broker B2 (via the on-demand +connector).</p> +<dl class="docutils"> +<dt>Examples of addresses that “begin with ‘b2’” include:</dt> +<dd><ul class="first last simple"> +<li>b2</li> +<li>b2/queues</li> +<li>b2/queues/app1</li> +</ul> +</dd> +</dl> +<p>When the on-demand connector is configured, router Ra establishes a +connection to the broker. Once the connection is open, Ra tells the +other routers (Rp and Rb) that it is a valid destination for +link-routes to the “b2” prefix. This means that sender or receiver +links attached to Rb or Rp will be routed via the shortest path to Ra +where they are then routed outbound to the broker B2.</p> +<p>On Rp and Rb, it is advisable to add the following configuration:</p> +<div class="highlight-python"><div class="highlight"><pre>linkRoutePattern { + prefix: b2 +} +</pre></div> +</div> +<p>This configuration tells the routers that link-routing is intended to +be available for targets and sources starting with “b2”. This is +important because it is possible that B2 might be unavailable or shut +off. If B2 is unreachable, Ra will not advertize itself as a +destination for “b2” and the other routers might never know that +“b2” was intended for link-routing.</p> +<p>The above configuration allows Rb and Rp to reject attaches that +should be routed to B2 with an error message that indicates that there +is no route available to the destination.</p> +</div> +</div> + --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
