You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by tr...@apache.org on 2013/10/25 20:54:16 UTC
svn commit: r1535817 - in /qpid/site:
docs/components/dispatch-router/index.html
docs/components/dispatch-router/release-0.1.html
input/components/dispatch-router/index.md
input/components/dispatch-router/release-0.1.md
Author: tross
Date: Fri Oct 25 18:54:16 2013
New Revision: 1535817
URL: http://svn.apache.org/r1535817
Log:
QPID-5001 - Added a page for the 0.1 release.
Added:
qpid/site/docs/components/dispatch-router/release-0.1.html
qpid/site/input/components/dispatch-router/release-0.1.md
Modified:
qpid/site/docs/components/dispatch-router/index.html
qpid/site/input/components/dispatch-router/index.md
Modified: qpid/site/docs/components/dispatch-router/index.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/components/dispatch-router/index.html?rev=1535817&r1=1535816&r2=1535817&view=diff
==============================================================================
--- qpid/site/docs/components/dispatch-router/index.html (original)
+++ qpid/site/docs/components/dispatch-router/index.html Fri Oct 25 18:54:16 2013
@@ -58,10 +58,13 @@ and brokers.</p>
<tbody>
<tr><td><em>Platforms</em></td><td>Linux</td></tr>
<tr><td><em>AMQP versions</em></td><td>1.0</td></tr>
+<tr><td><em>Download</em></td><td><a href="http://people.apache.org/~tross/qpid-dispatch-0.1rc1/">http://people.apache.org/~tross/qpid-dispatch-0.1rc1/</a></td></tr>
<tr><td><em>Source location</em></td><td><a href="http://svn.apache.org/repos/asf/qpid/dispatch/trunk/">http://svn.apache.org/repos/asf/qpid/dispatch/trunk/</a></td></tr>
</tbody>
</table>
+<p><a href="release-0.1.html">What can you do with Qpid Dispatch 0.1?</a></p>
+
<h2 id="overview">Overview</h2>
<p>The Dispatch router is an AMQP router that provides advanced interconnect for AMQP.
Added: qpid/site/docs/components/dispatch-router/release-0.1.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/components/dispatch-router/release-0.1.html?rev=1535817&view=auto
==============================================================================
--- qpid/site/docs/components/dispatch-router/release-0.1.html (added)
+++ qpid/site/docs/components/dispatch-router/release-0.1.html Fri Oct 25 18:54:16 2013
@@ -0,0 +1,305 @@
+<!DOCTYPE html>
+<!--
+ -
+ - 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.
+ -
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>Qpid Dispatch Release 0.1 - Apache Qpid™</title>
+ <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+ <link rel="stylesheet" href="http://qpid.apache.org/site.css" type="text/css"/>
+ <link rel="stylesheet" href="http://qpid.apache.org/pygments.css" type="text/css"/>
+ <!--[if lte IE 8]>
+ <link rel="stylesheet" href="http://qpid.apache.org/ie.css" type="text/css"/>
+ <![endif]-->
+ <script type="text/javascript" src="http://qpid.apache.org/site.js"></script>
+ </head>
+ <body>
+ <div id="content">
+ <div id="top">
+ <a id="search-link" href="http://qpid.apache.org/search.html"><img width="22" height="16" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABUAAAAQCAYAAAD52jQlAAABmklEQVQ4y2P4//8/A7UxpkBoAxtPaIMTb2hdKW9I/WLe0Pp2nrC6YO7IKnGyDOUObTAAGnIRiP9j4oZPQJxGkqF8YXWRQE2/oAY84Q1rmMETUpfOF9LQBBQ7jGTBaqIM5YyolgUq/gjWBDRMxK+MF10hX0hdNFwNAReDCaCidVBXbManGGowJCgCK4VxGgoEjDAX8IfWKBLyGlDdSajBfjgN5Q2tUYe68jExkQBMEd1g9SH1rTgN5Q+tc4UaepwYQ/lC6/Khhi7GaShPYIMY1NDPDA0NTARdGtYwD2JoXTGBiKp/DFIIdIU3PgOFohv4gOqegtQCM4QjXkOBOagOlj75QhuE8ETSfKT0+pontK5aMLScH6uhDGlprEDDzkENfsAdUueMrIgrokEKKLcRKg/KIKeRDP8IzsrAYMTMUcE1qgiDwfgtEO8H4tvIBgDVRIGzdFiDC9CCfUjZ+BtvSIMPRt4HuzisoQGo6CVa3v8O1LQJlPMwg6TWEpRpoOGcjbWUgmFw1g2r8+UOr9VncGhgIZjfQ0OZYWwAIBYjaUYze6wAAAAASUVORK5CYII="/></a>
+
+ <ul id="global-navigation">
+ <li><a id="logotype" href="http://qpid.apache.org/index.html">Apache Qpid<sup>™</sup></a></li>
+ <li><a href="http://qpid.apache.org/download.html">Download</a></li>
+ <li><a href="http://qpid.apache.org/documentation.html">Documentation</a></li>
+ <li><a href="http://qpid.apache.org/discussion.html">Discussion</a></li>
+ <li><a href="http://qpid.apache.org/issues.html">Issues</a></li>
+ <li><a href="http://qpid.apache.org/source-code.html">Source Code</a></li>
+ <li><a href="http://qpid.apache.org/resources.html">More Resources</a></li>
+ </ul>
+ </div>
+ <div id="middle">
+ <ul id="path-navigation"><li><a href="http://qpid.apache.org/components/index.html">Components</a></li><li><a href="http://qpid.apache.org/components/dispatch-router/index.html">Dispatch Router</a></li><li>Qpid Dispatch Release 0.1</li></ul>
+ <h1 id="qpid-dispatch-release-01">Qpid Dispatch Release 0.1</h1>
+
+<h2 id="system-requirements-and-dependencies">System Requirements and Dependencies</h2>
+
+<ul>
+<li>Qpid Dispatch will only build and run on Posix-based operating systems (Linux, et. al.)</li>
+<li>Qpid Proton version 0.5 must be installed (including the Python bindings) to build Qpid Dispatch</li>
+</ul>
+
+<h2 id="building-testing-and-installing">Building, Testing, and Installing</h2>
+
+<p>Download and extract the source tar file:</p>
+
+<pre><code>$ wget http://people.apache.org/~tross/qpid-dispatch-0.1rc1/qpid-dispatch-0.1.tar.gz
+$ tar -xzf qpid-dispatch-0.1.tar.gz
+</code></pre>
+
+<p>Source the build configuration and create a build directory:</p>
+
+<pre><code>$ cd qpid-dispatch-0.1
+$ source config.sh
+$ mkdir build
+</code></pre>
+
+<p>Configure and build the libraries and executables:</p>
+
+<pre><code>$ cd build
+$ cmake ..
+$ make
+</code></pre>
+
+<p>Run the regression test suite:</p>
+
+<pre><code>$ make test
+</code></pre>
+
+<p>If you want to see more detail on which tests are running in the regression suite, use the
+following command:</p>
+
+<pre><code>$ ctest -VV
+</code></pre>
+
+<p>Install the artifacts:</p>
+
+<pre><code>$ sudo make install
+</code></pre>
+
+<h2 id="configuration">Configuration</h2>
+
+<p>The default configuration file is installed in
+<em>build-prefix</em>/etc/qpid/qpid-dxrouter.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 /etc/qpid/qpid-dxrouter.conf 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:</p>
+
+<pre><code>$ qpid-dxrouterd
+</code></pre>
+
+<h2 id="client-compatibility">Client Compatibility</h2>
+
+<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>
+<tbody>
+<tr><td><em>Client</em></td><td><em>Notes</em></td></tr>
+<tr><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><td>Proton Messenger</td><td>Messenger works with Dispatch Router. As of version 0.5 of Proton, Messenger does not yet support dynamic sources for receiver links. Because of this, the dynamic reply-to feature is not available through Messenger. For more information, see <a href="https://issues.apache.org/jira/browse/PROTON-439">https://issues.apache.org/jira/browse/PROTON-439</a>.</td></tr>
+</tbody>
+</table>
+
+<h2 id="tools">Tools</h2>
+
+<p>Installed with the Dispatch Router kit is a command line tool called <em>qdstat</em>. This tool
+can be used to view manageable data inside Dispatch Router. The following options are
+useful for seeing that the router is doing:</p>
+
+<table>
+<tbody>
+<tr><td><em>Option</em></td><td><em>Description</em></td></tr>
+<tr><td>-l</td><td>Print a list of AMQP links attached to the router. Links are unidirectional. Outgoing links are usually associated with a subscription address. The tool distinguishes between <em>endpoint</em> links and <em>router</em> links. Endpoint links are attached to clients using the router. Router links are attached to other routers in a network of routers.</td></tr>
+<tr><td>-a</td><td>Print a list of addresses known to the router.</td></tr>
+<tr><td>-n</td><td>Print a list of known routers in the network.</td></tr>
+</tbody>
+</table>
+
+<h2 id="features-and-examples">Features and Examples</h2>
+
+<h3 id="standalone-and-interior-modes">Standalone and Interior Modes</h3>
+
+<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>
+
+<pre><code>$ qdstat -a
+Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 1 0 0 1 0
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+</code></pre>
+
+<p>Note that there are two known addresses. <em>$management</em> is the address of the router's embedded management agent. <em>temp.reply-address/0001</em> is the 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 two additional addresses which are used for inter-router communication:</p>
+
+<pre><code>$ qdstat -a
+Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 1 0 0 1 0
+ local qdxhello Y 0 0 0 0 0 0 38
+ local qdxrouter Y 0 0 0 0 0 0 2
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+</code></pre>
+
+<h3 id="mobile-subscribers">Mobile Subscribers</h3>
+
+<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>recv.py</em> example receiver:</p>
+
+<pre><code>$ recv.py amqp://0.0.0.0/my-address
+</code></pre>
+
+<p>This command creates a receiving link cubscribed to the specified address. To verify the
+subscription:</p>
+
+<pre><code>$ qdstat -a
+Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 2 0 0 2 0
+ mobile my-address 1 0 0 0 0 0 0
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+</code></pre>
+
+<p>You can then, in a separate command window, run a sender to produce messages to that
+address:</p>
+
+<pre><code>$ send.py -a amqp://0.0.0.0/my-address
+</code></pre>
+
+<h3 id="dynamic-reply-to">Dynamic Reply-To</h3>
+
+<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>
+
+<pre><code>#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();
+}
+</code></pre>
+
+<h2 id="known-issues-and-limitations">Known Issues and Limitations</h2>
+
+<p>This is an early test release. It is expected that users will find bugs and other
+various instabilities. The main goal of this release is to prove that the process can be
+run and that users can demonstrate basic functionality as described in this document.
+Nevertheless, the following are known issues with the 0.1 release:</p>
+
+<ul>
+<li>The qdstat utility shows a number of unsupported options when the -h/--help option is used.</li>
+<li>Subscriber addresses are not always cleaned up after a consumer disconnects. See
+<a href="https://issues.apache.org/jira/browse/QPID-4853">https://issues.apache.org/jira/browse/QPID-4853</a> and
+<a href="https://issues.apache.org/jira/browse/QPID-4964">https://issues.apache.org/jira/browse/QPID-4964</a>.</li>
+<li>Dispatch Router does not currently use the target address of a client's sender link to
+route messages. It only looks at the "to" field in the message's headers. See
+<a href="https://issues.apache.org/jira/browse/QPID-5175">https://issues.apache.org/jira/browse/QPID-5175</a>.</li>
+<li>The qdstat tool is built over Proton Messenger. Because Messenger does not yet support
+dynamic terminus, the tool uses the mobile address "temp.reply-address/0001" as its
+reply address. This is a temporary hack that will be fixed once Proton 0.6 becomes
+available.</li>
+<li>All subscription sources are treated as multicast addresses. There is currently no
+facility for provisioning different types of addresses. Multicast means that if there
+are multiple subscribers to the same address, they will all receive a copy of each
+message sent to that address.</li>
+<li>SSL connectors and listeners are supported but very lightly (and not recently) tested.</li>
+<li>SASL authentication is not currently integrated into any authentication framework. Use
+ANONYMOUS for testing.</li>
+</ul>
+
+ </div>
+ <div id="bottom">
+ <ul id="apache-navigation">
+ <li><a href="http://www.apache.org/">Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/">License</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks!</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ <li><a href="http://www.apache.org/"><img id="apache-feather" width="48" height="14" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAC4AAAAOCAYAAABQFS4BAAAFnElEQVRIx83S22ukdx3H8e/v8Pyew5xnsrMJSZNsmm4PW91uL5ZWhIK9EA/Fq8Uiite9EuzVFhbxoqvd7kWLVEWEuioqpQgVtmpFssZtabpR9xCb7uQwmexMspPM5JmZ5/w8v9/v64UtiCi2StX3X/CCz4fMz8w8vN5qLSGihnf7ypkzdw333Eeaq43f/G7xtRb8H0bOnz//+He/9cLjCHpZEfL9ZrN5+9wLL55GUJ/f2W7B3M+WnzZRfqmAukA0jgpVfu1NHF1dGHZ+abbnswVckP8T+Orq6tEwjJ5/9plvlv5wZflO1PriY6dOYcwKX6xWyli/uLUaRf2jdwRUTBGl+kL6PA5HlVGQ2zNVK7T0WlJhr1wW6hcvLizE/zU4IsLS0lKxVjv09dXVP3/5RxcuHNy4dn18/r77LCIKOBFN+XWds4uQcuEOCKOZOr6b8O6E0OV+AGUtVd+I99JS4ks3XWncgctqlv36qe+9dvVDh79Xo9E4ufzH61/b6e5/YnHxEvY7bYPGNs5Wj+s8q4GdY7TkR8gxFGNdATiZKifwyHTXBZnPqZR4EScq9aNQxfPkem8YvVPhxhu/Pch+9YM/LQw+NPgTp0/PVuzydxTwh6M4sk9gLrj51nZxhwWqPdwgeXFYVcQkpdqgRlbmDhI1z3sqsyjPp4GquSMSCIrTUUATJlJSSKMeCePJ7TTr5OTQrBsH7JAY9kDK3n504WK7/ebi2tr+fww/e/bcZ6rj489YljNj2zYUnv6x50VpXRoFFGmFL9QTKR2qtocbdDAI+HhlBkp0QumUkgckI/0q6OPuEHrlHFaTEea
TGHUA3MwzXXB9Gtg69axcaoYBt+NwEN7N/L0idvsr2TtpPrnCHilcOn32lfUPDG82mx/dat366sR4XW9ttUz9k1c/LV5fLylb4DGX0x/OjeuwMh0DoKF9yg/EjhrpHu4MtlgYKFIvTslJo0oTXcGTI5f2ihVdFEBEGGhOJB3latqWrprrBwa3Ez0kDl5lR8jd5oZv0CAd21RsO99ruyet55e8Wy+/9NKK/77g7/78HinlpmmaH9Fan+ldfvVT8Po1VlpL2VVq60IM6TDTzIkOGe44xBEXYOuEbViCeSyRcerhXtBlu26blewxnTcPY44yQLRBgca52KYz6BMTDL1sztM7jU00MiWjxOEP8S5WICK7EtrJgcvg0ULXOZrnmxitdQ+it/3B8LlvfPv37j+E/33r6xvnR8POF8JOozh6e004FzehdluzQbFM0VRxzAUSRJIhwX6GlOdySgJhocH5fhqgb9kqIgAcQgiYAXE2Yv1gQJRCYMjJlEI5yh/GIzo05oNMdUSRTSovPTaMhHvqcBpMUmIWUMkMItRhZ9f1fvrEkz8/9y/hf12heZxz/KTS+nO3b63cG/VvOvLyBoOmr8enLOoveiT3MQfxUkC6JigClDAF1NAKUuFgGSg2c4bUjINODbZPJF3nd9H7RUdFQUgaloVjmYcDs05M1YWBClFUGZs8kqpqxQGDE0oBkHOiewM/VFl87X3B/7Zms/mYUvjZKPIe8lu7VSn2S8mVthGzgCIJCH2jD3yoSBpr4tQYhAQwvydJDYnuGEwxhcxWSPYYp9IXMCdivWMbmACiiRrUkLKyleq+JVBMC6ofFbpUNQEVAEpJGzsuuAMVfWD4e7XbbdtPknsp4oME8R4AOg2g61HgV73RIGdorr1GK+/vbrPEyuxiMyJwgsvkUo+jDgxdtzANU8PeylT+42PS24iQFBixcijkyInh/kqaBcpwWiM4eNAE7gjl5OuqUDsWT0zO7P7b8H/WjRs3
Koh4qFwuZ1mWPYAIJwCwCAA5JKREEPJKqRnKmUcQbSCEESAeAqSISAmBKiKuEIAuALUQ9BglBBExopSuUkpfnp2dvfkX6a5m0ZqSUXAAAAAASUVORK5CYII="/></a></li>
+ </ul>
+
+ <p id="legal">
+ Apache Qpid, Messaging built on AMQP; Copyright © 2013
+ The Apache Software Foundation; Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
+ License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
+ Proton, Apache, the Apache feather logo, and the Apache Qpid
+ project logo are trademarks of The Apache Software
+ Foundation; All other marks mentioned may be trademarks or
+ registered trademarks of their respective owners
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Modified: qpid/site/input/components/dispatch-router/index.md
URL: http://svn.apache.org/viewvc/qpid/site/input/components/dispatch-router/index.md?rev=1535817&r1=1535816&r2=1535817&view=diff
==============================================================================
--- qpid/site/input/components/dispatch-router/index.md (original)
+++ qpid/site/input/components/dispatch-router/index.md Fri Oct 25 18:54:16 2013
@@ -26,8 +26,10 @@ and brokers.
|| *Platforms* || Linux ||
|| *AMQP versions* || 1.0 ||
-;; || *Download* || *Coming soon* ||
+ || *Download* || <http://people.apache.org/~tross/qpid-dispatch-0.1rc1/> ||
|| *Source location* || <http://svn.apache.org/repos/asf/qpid/dispatch/trunk/> ||
+
+[What can you do with Qpid Dispatch 0.1?](release-0.1.html)
## Overview
Added: qpid/site/input/components/dispatch-router/release-0.1.md
URL: http://svn.apache.org/viewvc/qpid/site/input/components/dispatch-router/release-0.1.md?rev=1535817&view=auto
==============================================================================
--- qpid/site/input/components/dispatch-router/release-0.1.md (added)
+++ qpid/site/input/components/dispatch-router/release-0.1.md Fri Oct 25 18:54:16 2013
@@ -0,0 +1,227 @@
+;;
+;; 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.
+;;
+
+# Qpid Dispatch Release 0.1
+
+## System Requirements and Dependencies
+
+ - Qpid Dispatch will only build and run on Posix-based operating systems (Linux, et. al.)
+ - Qpid Proton version 0.5 must be installed (including the Python bindings) to build Qpid Dispatch
+
+## Building, Testing, and Installing
+
+Download and extract the source tar file:
+
+ $ wget http://people.apache.org/~tross/qpid-dispatch-0.1rc1/qpid-dispatch-0.1.tar.gz
+ $ tar -xzf qpid-dispatch-0.1.tar.gz
+
+Source the build configuration and create a build directory:
+
+ $ cd qpid-dispatch-0.1
+ $ source config.sh
+ $ mkdir build
+
+Configure and build the libraries and executables:
+
+ $ cd build
+ $ cmake ..
+ $ make
+
+Run the regression test suite:
+
+ $ make test
+
+If you want to see more detail on which tests are running in the regression suite, use the
+following command:
+
+ $ ctest -VV
+
+Install the artifacts:
+
+ $ sudo make install
+
+## Configuration
+
+The default configuration file is installed in
+_build-prefix_/etc/qpid/qpid-dxrouter.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 /etc/qpid/qpid-dxrouter.conf 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.
+
+To run the router, invoke the executable:
+
+ $ qpid-dxrouterd
+
+## Client Compatibility
+
+Dispatch Router should, in theory, work with any client that is compatible with AMQP 1.0.
+The following clients have been tested:
+
+ || *Client* || *Notes* ||
+ || qpid::messaging || 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. ||
+ || Proton Messenger || Messenger works with Dispatch Router. As of version 0.5 of Proton, Messenger does not yet support dynamic sources for receiver links. Because of this, the dynamic reply-to feature is not available through Messenger. For more information, see <https://issues.apache.org/jira/browse/PROTON-439>. ||
+
+## Tools
+
+Installed with the Dispatch Router kit is a command line tool called *qdstat*. This tool
+can be used to view manageable data inside Dispatch Router. The following options are
+useful for seeing that the router is doing:
+
+ || *Option* || *Description* ||
+ || -l || Print a list of AMQP links attached to the router. Links are unidirectional. Outgoing links are usually associated with a subscription address. The tool distinguishes between _endpoint_ links and _router_ links. Endpoint links are attached to clients using the router. Router links are attached to other routers in a network of routers. ||
+ || -a || Print a list of addresses known to the router. ||
+ || -n || Print a list of known routers in the network. ||
+
+## Features and Examples
+
+### Standalone and Interior Modes
+
+The router can operate stand-alone or as a node in a network of routers. The mode is
+configured in the _router_ 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.
+
+If your router is running in stand-alone mode, _qdstat -a_ will look like the following:
+
+ $ qdstat -a
+ Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 1 0 0 1 0
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+
+Note that there are two known addresses. _$management_ is the address of the router's embedded management agent. _temp.reply-address/0001_ is the address of the _qdstat_ client making requests to the agent.
+
+If you change the mode to interior and restart the processs, the same command will yield two additional addresses which are used for inter-router communication:
+
+ $ qdstat -a
+ Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 1 0 0 1 0
+ local qdxhello Y 0 0 0 0 0 0 38
+ local qdxrouter Y 0 0 0 0 0 0 2
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+
+
+### Mobile Subscribers
+
+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.
+
+To illustrate a subscription on a stand-alone router, you can use the examples that are
+provided with Qpid Proton. Using the _recv.py_ example receiver:
+
+ $ recv.py amqp://0.0.0.0/my-address
+
+This command creates a receiving link cubscribed to the specified address. To verify the
+subscription:
+
+ $ qdstat -a
+ Router Addresses
+ class address in-proc local remote in out thru to-proc from-proc
+ ============================================================================================
+ local $management Y 0 0 2 0 0 2 0
+ mobile my-address 1 0 0 0 0 0 0
+ mobile temp.reply-address/0001 1 0 0 0 0 0 0
+
+You can then, in a separate command window, run a sender to produce messages to that
+address:
+
+ $ send.py -a amqp://0.0.0.0/my-address
+
+### Dynamic Reply-To
+
+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.
+
+ #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();
+ }
+
+
+## Known Issues and Limitations
+
+This is an early test release. It is expected that users will find bugs and other
+various instabilities. The main goal of this release is to prove that the process can be
+run and that users can demonstrate basic functionality as described in this document.
+Nevertheless, the following are known issues with the 0.1 release:
+
+ - The qdstat utility shows a number of unsupported options when the -h/--help option is used.
+ - Subscriber addresses are not always cleaned up after a consumer disconnects. See
+ <https://issues.apache.org/jira/browse/QPID-4853> and
+ <https://issues.apache.org/jira/browse/QPID-4964>.
+ - Dispatch Router does not currently use the target address of a client's sender link to
+ route messages. It only looks at the "to" field in the message's headers. See
+ <https://issues.apache.org/jira/browse/QPID-5175>.
+ - The qdstat tool is built over Proton Messenger. Because Messenger does not yet support
+ dynamic terminus, the tool uses the mobile address "temp.reply-address/0001" as its
+ reply address. This is a temporary hack that will be fixed once Proton 0.6 becomes
+ available.
+ - All subscription sources are treated as multicast addresses. There is currently no
+ facility for provisioning different types of addresses. Multicast means that if there
+ are multiple subscribers to the same address, they will all receive a copy of each
+ message sent to that address.
+ - SSL connectors and listeners are supported but very lightly (and not recently) tested.
+ - SASL authentication is not currently integrated into any authentication framework. Use
+ ANONYMOUS for testing.
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org