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/12/11 22:57:11 UTC
svn commit: r1550281 - in /qpid/dispatch/trunk/doc/book: addressing.md
amqp-mapping.md index.md release-0.1.md
Author: tross
Date: Wed Dec 11 21:57:11 2013
New Revision: 1550281
URL: http://svn.apache.org/r1550281
Log:
NO-JIRA - Copied the Dispatch documentation from the main site to the project site.
Added:
qpid/dispatch/trunk/doc/book/addressing.md
qpid/dispatch/trunk/doc/book/amqp-mapping.md
qpid/dispatch/trunk/doc/book/index.md
qpid/dispatch/trunk/doc/book/release-0.1.md
Added: qpid/dispatch/trunk/doc/book/addressing.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/addressing.md?rev=1550281&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/addressing.md (added)
+++ qpid/dispatch/trunk/doc/book/addressing.md Wed Dec 11 21:57:11 2013
@@ -0,0 +1,112 @@
+;;
+;; 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.
+;;
+
+# Dispatch Addressing
+
+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 `to` and `reply-to`
+fields of a message's properties. They are also used during the creation of
+links in the `address` field of a `source` or a `target`.
+
+Addresses designate various kinds of entities in a messaging network:
+
+ - Endpoint processes that consume data or offer a service
+ - Topics that match multiple consumers to multiple producers
+ - Entities within a messaging broker:
+ - Queues
+ - Durable Topics
+ - Exchanges
+
+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.
+
+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.
+
+Address semantics include the following considerations:
+
+ - *Routing pattern* - direct, multicast, balanced
+ - *Routing mechanism* - message routed, link routed
+ - *Undeliverable action* - drop, hold and retry, redirect
+ - *Reliability* - N destinations, etc.
+
+## Routing patterns
+
+Routing patterns constrain the paths that a message can take across a network.
+
+ || *Pattern* || *Description* ||
+ || *Direct* || 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. ||
+ || *Multicast* || 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. ||
+ || *Balanced* || Balanced routing also allows multiple consumers to use the same address. In this case, messages (or links) 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. ||
+
+## Routing mechanisms
+
+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 *routing*:
+
+> In a network built of multiple routers connected by connections (i.e., nodes and
+> edges in a graph), *routing* determines which connection to use to send a message
+> directly to its destination or one step closer to its destination.
+
+Each router serves as the terminus of a collection of incoming and outgoing links.
+Some of the links are designated for message routing, and others are designated for
+link routing. In both cases, 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.
+
+### Message routing
+
+Message routing occurs upon delivery of a message and is done based on the address
+in the message's `to` field.
+
+When a delivery arrives on an incoming message-routing link, the router extracts the
+address from the delivered message's `to` 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.
+
+ || *Delivery* || *Handling* ||
+ || *pre-settled* || 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. ||
+ || *unsettled* || 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. ||
+
+### Link routing
+
+Link routing occurs when a new link is attached to the router across one of its AMQP connections.
+It is done based on the `target.address` field of an inbound link and the `source.address` field
+of an outbound link.
+
+Link routing uses the same routing table that message routing uses. The difference is that the
+routing occurs during the link-attach operation, and link attaches are propagated along the appropriate
+path to the destination. What results is a chain of links, connected end-to-end, from source to
+destination. It is similar to a *virtual circuit* in a telecom system.
+
+Each router in the chain holds pairs of link termini that are tied together. The router then simply
+exchanges all deliveries, delivery state changes, and link state changes between the two termini.
+
+The endpoints that use the link chain do not see any difference in behavior between a link chain and
+a single point-to-point link. All of the features available in the link protocol (flow control,
+transactional delivery, etc.) are available over a routed link-chain.
+
Added: qpid/dispatch/trunk/doc/book/amqp-mapping.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/amqp-mapping.md?rev=1550281&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/amqp-mapping.md (added)
+++ qpid/dispatch/trunk/doc/book/amqp-mapping.md Wed Dec 11 21:57:11 2013
@@ -0,0 +1,101 @@
+;;
+;; 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.
+;;
+
+# Dispatch AMQP Mapping
+
+Dispatch Router is an AMQP router and as such, it provides extensions,
+codepoints, and semantics for routing over AMQP. This page documents
+the details of Dispatch Router's use of AMQP.
+
+
+## Delivery Annotations
+
+The following Delivery Annotation fields are defined by Dispatch Router:
+
+ || *Field* || *Type* || *Description* ||
+ || <span style="white-space: nowrap;">x-opt-qd.ingress</span> || string || 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. ||
+ || <span style="white-space: nowrap;">x-opt-qd.trace</span> || list of string || 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. ||
+ || x-opt-qd.to || string || 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 *to* 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. ||
+
+
+## Source/Target Capabilities
+
+The following Capability values are used in Sources and Targets.
+
+ || *Capability* || *Description* ||
+ || qd.router || This capability is added to sources and targets that are used for inter-router message exchange. ||
+
+
+## Addresses and Address Formats
+
+The following AMQP addresses and address patterns are used within Dispatch Router.
+
+### Address Patterns
+
+ || *Pattern* || *Description* ||
+ || /_local/<addr> || An address that references a locally attached endpoint. Messages using this address pattern shall not be routed over more than one link. ||
+ || <span style="white-space: nowrap;">/_topo/<area>/<router>/<addr></span> || 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. ||
+ || /<addr> || 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. ||
+
+### Supported Addresses
+
+ || *Address* || *Description* ||
+ || /_local/$management || 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. ||
+ || <span style="white-space: nowrap;">/_topo/0/Router.E/agent</span> || 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. ||
+ || /_local/qdhello || 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. ||
+ || /_local/qdrouter || The router entity in each of the connected routers. This address is used by a router to communicate with other routers in the network. ||
+ || <span style="white-space: nowrap;">/_topo/0/Router.E/qdxrouter</span> || 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. ||
+
+## Implementation of the AMQP Management Specification
+
+Qpid Dispatch is manageable remotely via AMQP. It is compliant to a limited degree with the emerging AMQP Management specification. This section provides the details of what is supported and what is not and what is planned and what is not.
+
+Non-compliance occurs for one of the following reasons:
+
+ - Implementation of an optional feature is not planned
+ - Implementation is not complete as of the current time
+ - The specified operation is considered suboptimal or unimplementable. In all of these cases, an issue is pending with the AMQP Technical Committee.
+
+### Compliance Matrix
+
+ || *Operation/Feature* || *Requirement* || *Supported* || *Remarks* ||
+ || CREATE || Should || No || There are currently no Manageable Entities for which this is appropriate ||
+ || READ || Should || No || Not yet implemented ||
+ || UPDATE || Should || No || There are currently no Manageable Entities for which this is appropriate ||
+ || DELETE || Should || No || There are currently no Manageable Entities for which this is appropriate ||
+ || READALL || Should || No || A non-standard version of this operation is supported that retrieves data from all entities of a type. There is an outstanding issue raised with the AMQP Technical Committee to address this requirement. ||
+ || DISCOVER-NAMES || Should || No || Not yet implemented ||
+ || DISCOVER-TYPES || Should || Yes || There are no types that implement base types ||
+ || DISCOVER-OPERATIONS || Should || Yes || ||
+ || DISCOVER-MGMT-NODES || Should || Yes || This operation yields the addresses of all of the router nodes in the known network ||
+ || REGISTER || May || Not Planned || The router has a specific way to discover peers that does not involve this operation ||
+ || DEREGISTER || May || Not Planned || The router has a specific way to discover peers that does not involve this operation ||
+
+### Manageable Entities
+
+ || *Type Name* || *Description* ||
+ || org.apache.qpid.dispatch.allocator || Per-type memory allocation statistics ||
+ || org.apache.qpid.dispatch.connection || Connections to the router's container ||
+ || org.apache.qpid.dispatch.container || General state and statistics for the AMQP container ||
+ || org.apache.qpid.dispatch.container.node_type || Description of registered node types ||
+ || org.apache.qpid.dispatch.container.node || Description of registered nodes in the container ||
+ || org.apache.qpid.dispatch.router || General state and statistics for the router node ||
+ || org.apache.qpid.dispatch.router.link || Per-link state and statistics for links attached to the router node ||
+ || org.apache.qpid.dispatch.router.node || Per-node state and statistics for remote router nodes in the known network ||
+ || org.apache.qpid.dispatch.router.address || Per-address state and statistics for addresses known to this router ||
Added: qpid/dispatch/trunk/doc/book/index.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/index.md?rev=1550281&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/index.md (added)
+++ qpid/dispatch/trunk/doc/book/index.md Wed Dec 11 21:57:11 2013
@@ -0,0 +1,106 @@
+;;
+;; 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.
+;;
+
+# Dispatch Router
+
+A lightweight message router, written in C and built on
+[Qpid Proton](@site-url@/proton/index.html), that provides flexible
+and scalable interconnect between AMQP endpoints or between endpoints
+and brokers.
+
+ || *Platforms* || Linux ||
+ || *AMQP versions* || 1.0 ||
+ || *Download* || <http://people.apache.org/~tross/qpid-dispatch-0.1rc3/> ||
+ || *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
+
+The Dispatch router is an AMQP router that provides advanced interconnect for AMQP.
+It is *not* a broker. It will never assume ownership of a message. It will,
+however, propagate settlement and disposition across a network such that delivery
+guarantees are met.
+
+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.
+
+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.
+
+## Benefits
+
+ - Simplifies connectivity
+ - An endpoint can do all of its messaging through a single transport connection
+ - Avoid opening holes in firewalls for incoming connections
+ - Simplifies reliability
+ - Reliability and availability are provided using redundant topology, not server clustering
+ - Reliable end-to-end messaging without persistent stores
+ - Use a message broker only when you need store-and-forward semantics
+
+## Features
+
+<div class="two-column" markdown="1">
+
+ - Supports arbitrary topology - no restrictions on redundancy
+ - Automatic route computation - adjusts quickly to changes in topology
+ - Cost-based route computation
+ - [Rich addressing semantics](addressing.html)
+ - Security
+
+</div>
+
+## Technical Details
+
+<div class="two-column" markdown="1">
+
+ - [Usage of AMQP](amqp-mapping.html)
+
+</div>
+
+## Issues
+
+For more information about finding and reporting bugs, see
+[Qpid issues](@site-url@/issues.html).
+
+<div class="indent">
+ <form id="jira-search-form">
+ <input type="hidden" name="jql" value="project = QPID and component = 'Qpid Dispatch' and text ~ '{}' order by updatedDate desc"/>
+ <input type="text" name="text"/>
+ <button type="submit">Search</button>
+ </form>
+</div>
+
+<div class="two-column" markdown="1">
+
+ - [Open bugs](http://issues.apache.org/jira/issues/?jql=resolution+%3D+EMPTY+and+issuetype+%3D+%22Bug%22+and+component+%3D+%22Qpid+Dispatch%22+and+project+%3D+%22QPID%22)
+ - [Fixed bugs](http://issues.apache.org/jira/issues/?jql=resolution+%3D+%22Fixed%22+and+issuetype+%3D+%22Bug%22+and+component+%3D+%22Qpid+Dispatch%22+and+project+%3D+%22QPID%22)
+ - [Requested enhancements](http://issues.apache.org/jira/issues/?jql=resolution+%3D+EMPTY+and+issuetype+in+%28%22New+Feature%22%2C+%22Improvement%22%29+and+component+%3D+%22Qpid+Dispatch%22+and+project+%3D+%22QPID%22)
+ - [Completed enhancements](http://issues.apache.org/jira/issues/?jql=resolution+%3D+%22Fixed%22+and+issuetype+in+%28%22New+Feature%22%2C+%22Improvement%22%29+and+component+%3D+%22Qpid+Dispatch%22+and+project+%3D+%22QPID%22)
+ - [Report a bug](http://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=12310520&issuetype=1&priority=3&summary=[Enter%20a%20brief%20description]&components=12320398)
+ - [Request an enhancement](http://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=12310520&issuetype=4&priority=3&summary=[Enter%20a%20brief%20description]&components=12320398)
+ - [Jira summary page](http://issues.apache.org/jira/browse/QPID/component/12320398)
+
+</div>
Added: qpid/dispatch/trunk/doc/book/release-0.1.md
URL: http://svn.apache.org/viewvc/qpid/dispatch/trunk/doc/book/release-0.1.md?rev=1550281&view=auto
==============================================================================
--- qpid/dispatch/trunk/doc/book/release-0.1.md (added)
+++ qpid/dispatch/trunk/doc/book/release-0.1.md Wed Dec 11 21:57:11 2013
@@ -0,0 +1,298 @@
+;;
+;; 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.6 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.1rc3/qpid-dispatch-0.1.tar.gz
+ $ tar -xzf qpid-dispatch-0.1.tar.gz
+
+Source the build configuration:
+
+ $ cd qpid-dispatch-0.1
+ $ source config.sh
+
+Build and test the package. This will create two directories: 'build' and 'install'. Dispatch will be built in the 'build' directory
+and installed in the 'install' directory. The regression and system test suites will then be run against the installed bits.
+
+ $ bin/test.sh
+
+If you wish to change the build configuration, go into the build directory, use cmake to configure your build then rebuild and/or reinstall from there:
+
+ $ cd build
+ $ cmake ..
+ $ make
+ $ make install
+
+## Configuration
+
+The default configuration file is installed in
+_install-prefix_/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.
+
+To run the router, invoke the executable:
+
+ $ qdrouterd
+
+## 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. ||
+
+## 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. ||
+ || -c || Print a list of connections to the router. ||
+
+## 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
+ local temp.AY81ga 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.AY81ga_ is the temporary reply-to 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 qdhello Y 0 0 0 0 0 0 3
+ local qdrouter Y 0 0 0 0 0 0 1
+ local temp.khOpGb 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 subscribed 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 1 0 0 1 0
+ mobile my-address 1 0 0 0 0 0 0
+ local temp.fDt8_a 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();
+ }
+
+The equivalent program written in Python against the Proton Messenger API:
+
+ from proton import Messenger, Message
+
+ def main():
+ host = "0.0.0.0:5672"
+
+ messenger = Messenger()
+ messenger.start()
+ messenger.route("amqp:/*", "amqp://%s/$1" % host)
+ reply_subscription = messenger.subscribe("amqp:/#")
+ reply_address = reply_subscription.address
+
+ request = Message()
+ response = Message()
+
+ request.address = "amqp:/_local/$management"
+ request.reply_to = reply_address
+ request.properties = {u'operation' : u'DISCOVER-MGMT-NODES',
+ u'type' : u'org.amqp.management',
+ u'name' : u'self'}
+
+ messenger.put(request)
+ messenger.send()
+ messenger.recv()
+ messenger.get(response)
+
+ print "Response: %r" % response.body
+
+ messenger.stop()
+
+ main()
+
+
+## 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:
+
+ - Subscriber addresses are not always cleaned up after a consumer disconnects. See
+ <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>.
+ - 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.
+
+## Issues Addressed in this Release
+
+ - [QPID-4612](https://issues.apache.org/jira/browse/QPID-4612) Dispatch - Change server and container pattern to be consistent with other objects
+ - [QPID-4613](https://issues.apache.org/jira/browse/QPID-4613) Dispatch Message API Improvements
+ - [QPID-4614](https://issues.apache.org/jira/browse/QPID-4614) CTEST for Dispatch
+ - [QPID-4788](https://issues.apache.org/jira/browse/QPID-4788) Dispatch - Re-schedule of an "immediate" timer causes crash
+ - [QPID-4816](https://issues.apache.org/jira/browse/QPID-4816) dispatch-router crashes when incomplete (but valid) url specified by client.
+ - [QPID-4853](https://issues.apache.org/jira/browse/QPID-4853) Connectors are not closed when connections are closed cleanly
+ - [QPID-4913](https://issues.apache.org/jira/browse/QPID-4913) Dispatch - Add a configuration file reader to configure the service
+ - [QPID-4963](https://issues.apache.org/jira/browse/QPID-4963) Dispatch - Excessive latency in timers under light load
+ - [QPID-4967](https://issues.apache.org/jira/browse/QPID-4967) Dispatch - Distributed routing protocol to compute paths across a network of routers
+ - [QPID-4968](https://issues.apache.org/jira/browse/QPID-4968) Dispatch - Generalized framework for embedded Python modules
+ - [QPID-4974](https://issues.apache.org/jira/browse/QPID-4974) Dispatch - Improve the API for parsing and composing AMQP-typed fields
+ - [QPID-4997](https://issues.apache.org/jira/browse/QPID-4997) Dispatch - Thread safety issues in the usage of Proton
+ - [QPID-5001](https://issues.apache.org/jira/browse/QPID-5001) Dispatch - A web page on the site for the Dispatch Router component
+ - [QPID-5045](https://issues.apache.org/jira/browse/QPID-5045) Dispatch - Refactor the router data structures to allow both message-based and link-based routing that supports full link protocol
+ - [QPID-5064](https://issues.apache.org/jira/browse/QPID-5064) Dispatch - make-install doesn't install the Python artifacts
+ - [QPID-5066](https://issues.apache.org/jira/browse/QPID-5066) Dispatch - move Python code into the qpid.dispatch package
+ - [QPID-5068](https://issues.apache.org/jira/browse/QPID-5068) Dispatch - Internal feature to easily add and update Delivery Annotations
+ - [QPID-5096](https://issues.apache.org/jira/browse/QPID-5096) Dispatch - Install the configuration file
+ - [QPID-5097](https://issues.apache.org/jira/browse/QPID-5097) Dispatch - create a source tarball
+ - [QPID-5173](https://issues.apache.org/jira/browse/QPID-5173) [dispatch] cmake ignores overrides to CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH
+ - [QPID-5181](https://issues.apache.org/jira/browse/QPID-5181) Dispatch - Assign temporary source addresses for dynamic listener links
+ - [QPID-5185](https://issues.apache.org/jira/browse/QPID-5185) Move the qpid-dispatch.conf file to /etc/qpid
+ - [QPID-5186](https://issues.apache.org/jira/browse/QPID-5186) Installing Dispatch should also install the LICENSE, TODO and related files
+ - [QPID-5189](https://issues.apache.org/jira/browse/QPID-5189) Add a config.sh file for Qpid Dispatch to set an environment for running the router
+ - [QPID-5201](https://issues.apache.org/jira/browse/QPID-5201) Dispatch - Fix build errors in Release mode
+ - [QPID-5212](https://issues.apache.org/jira/browse/QPID-5212) Dispatch - Add management access to data in the router module
+ - [QPID-5213](https://issues.apache.org/jira/browse/QPID-5213) Dispatch - Add a CLI tool to display manageable data in Dispatch
+ - [QPID-5216](https://issues.apache.org/jira/browse/QPID-5216) Dispatch - Stabilization in anticipation of an early release
+ - [QPID-5218](https://issues.apache.org/jira/browse/QPID-5218) [dispatch] Crash when outgoing window > 0 and multiple subscribed Messenger clients
+ - [QPID-5220](https://issues.apache.org/jira/browse/QPID-5220) Dispatch - Define Modes of Operation for the router function
+ - [QPID-5221](https://issues.apache.org/jira/browse/QPID-5221) Dispatch - Configured connections can be annotated as to their role
+ - [QPID-5257](https://issues.apache.org/jira/browse/QPID-5257) Dispatch - Move the code from trunk/qpid/extras to dispatch
+ - [QPID-5258](https://issues.apache.org/jira/browse/QPID-5258) Dispatch - Prepare for Release 0.1
+ - [QPID-5267](https://issues.apache.org/jira/browse/QPID-5267) Examples aren't being installed
+ - [QPID-5310](https://issues.apache.org/jira/browse/QPID-5310) copy the correlationID into management replies
+ - [QPID-5313](https://issues.apache.org/jira/browse/QPID-5313) qpid-dxrouterd binary should install the /usr/sbin on *nix
+ - [QPID-5319](https://issues.apache.org/jira/browse/QPID-5319) Add ability to get list of connections through server management agent
+ - [QPID-5335](https://issues.apache.org/jira/browse/QPID-5335) Dispatch Python libraries need to install to a private directory.
+ - [QPID-5338](https://issues.apache.org/jira/browse/QPID-5338) The Dispatch top-level Python package should be renamed
+ - [QPID-5339](https://issues.apache.org/jira/browse/QPID-5339) Dispatch - Intermittent crashes during scripted six-node tests
+ - [QPID-5343](https://issues.apache.org/jira/browse/QPID-5343) Dispatch does not properly handle the drain protocol on senders.
+ - [QPID-5350](https://issues.apache.org/jira/browse/QPID-5350) Dispatch - Management queries that receive empty tables results in corrupt response
+ - [QPID-5351](https://issues.apache.org/jira/browse/QPID-5351) Settle on one prefix for Dispatch names
+ - [QPID-5352](https://issues.apache.org/jira/browse/QPID-5352) Installation of python code ignores prefix
+ - [QPID-5365](https://issues.apache.org/jira/browse/QPID-5365) Clean up file locations in Dispatch
+ - [QPID-5381](https://issues.apache.org/jira/browse/QPID-5381) Dispatch - Use dynamic source address for the reply-to in qdstat tool
+ - [QPID-5393](https://issues.apache.org/jira/browse/QPID-5393) Dispatch - Allow qdstat to query any router in the network from a connection
+ - [QPID-5397](https://issues.apache.org/jira/browse/QPID-5397) Dispatch - Crash occurs when linked deliveries are concurrently settled
+ - [QPID-5403](https://issues.apache.org/jira/browse/QPID-5403) Dispatch - The router-specific annotations have reserved keys
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org