content/components/dispatch-router/addressing.html - qpid-site - Git at Google

 <!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>Dispatch Addressing - Apache Qpid&#8482;</title>
     <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
     <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
     <link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
     <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
     <script type="text/javascript">var _deferredFunctions = [];</script>
     <script type="text/javascript" src="/deferred.js" defer="defer"></script>
     <!--[if lte IE 8]>
       <link rel="stylesheet" href="/ie.css" type="text/css"/>
       <script type="text/javascript" src="/html5shiv.js"></script>
     <![endif]-->

     <!-- Redirects for `go get` and godoc.org -->
     <meta name="go-import"
           content="qpid.apache.org git https://gitbox.apache.org/repos/asf/qpid-proton.git"/>
     <meta name="go-source"
           content="qpid.apache.org
 https://github.com/apache/qpid-proton/blob/go1/README.md
 https://github.com/apache/qpid-proton/tree/go1{/dir}
 https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
   </head>
   <body>
     <div id="-content">
       <div id="-top" class="panel">
         <a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>

         <a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>

         <ul id="-global-navigation">
           <li><a id="-logotype" href="/index.html">Apache Qpid<sup>&#8482;</sup></a></li>
           <li><a href="/documentation.html">Documentation</a></li>
           <li><a href="/download.html">Download</a></li>
           <li><a href="/discussion.html">Discussion</a></li>
         </ul>
       </div>

       <div id="-menu" class="panel" style="display: none;">
         <div class="flex">
           <section>
             <h3>Project</h3>

             <ul>
               <li><a href="/overview.html">Overview</a></li>
               <li><a href="/components/index.html">Components</a></li>
               <li><a href="/releases/index.html">Releases</a></li>
             </ul>
           </section>

           <section>
             <h3>Messaging APIs</h3>

             <ul>
               <li><a href="/proton/index.html">Qpid Proton</a></li>
               <li><a href="/components/jms/index.html">Qpid JMS</a></li>
               <li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
             </ul>
           </section>

           <section>
             <h3>Servers and tools</h3>

             <ul>
               <li><a href="/components/broker-j/index.html">Broker-J</a></li>
               <li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
               <li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
             </ul>
           </section>

           <section>
             <h3>Resources</h3>

             <ul>
               <li><a href="/dashboard.html">Dashboard</a></li>
               <li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
               <li><a href="/resources.html">More resources</a></li>
             </ul>
           </section>
         </div>
       </div>

       <div id="-search" class="panel" style="display: none;">
         <form action="http://www.google.com/search" method="get">
           <input type="hidden" name="sitesearch" value="qpid.apache.org"/>
           <input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
           <button type="submit">Search</button>
           <a href="/search.html">More ways to search</a>
         </form>
       </div>

       <div id="-middle" class="panel">
         <ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/components/index.html">Components</a></li><li><a href="/components/dispatch-router/index.html">Dispatch Router</a></li><li>Dispatch Addressing</li></ul>

         <div id="-middle-content">
           <h1 id="dispatch-addressing">Dispatch Addressing</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 <code>to</code> and <code>reply-to</code>
 fields of a message's properties.  They are also used during the creation of
 links in the <code>address</code> field of a <code>source</code> or a <code>target</code>.</p>

 <p>Addresses designate various kinds of entities in a messaging network:</p>

 <ul>
 <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:
 <ul>
 <li>Queues</li>
 <li>Durable Topics</li>
 <li>Exchanges</li>
 </ul></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>
 <li><em>Routing pattern</em> - direct, multicast, balanced</li>
 <li><em>Routing mechanism</em> - message routed, link routed</li>
 <li><em>Undeliverable action</em> - drop, hold and retry, redirect</li>
 <li><em>Reliability</em> - N destinations, etc.</li>
 </ul>

 <h2 id="routing-patterns">Routing patterns</h2>

 <p>Routing patterns constrain the paths that a message can take across a network.</p>

 <table>
 <thead>
 <tr>
   <th>Pattern</th>
   <th>Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
   <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>
   <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>
   <td><em>Balanced</em></td>
   <td>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.</td>
 </tr>
 </tbody>
 </table>

 <h2 id="routing-mechanisms">Routing mechanisms</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>
   <p>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.</p>
 </blockquote>

 <p>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.</p>

 <h3 id="message-routing">Message routing</h3>

 <p>Message routing occurs upon delivery of a message and is done based on the address
 in the message's <code>to</code> field.</p>

 <p>When a delivery arrives on an incoming message-routing link, the router extracts the
 address from the delivered message's <code>to</code> 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>
 <thead>
 <tr>
   <th>Delivery</th>
   <th>Handling</th>
 </tr>
 </thead>
 <tbody>
 <tr>
   <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>
   <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>

 <h3 id="link-routing">Link routing</h3>

 <p>Link routing occurs when a new link is attached to the router across one of its AMQP connections.
 It is done based on the <code>target.address</code> field of an inbound link and the <code>source.address</code> field
 of an outbound link.</p>

 <p>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 <em>virtual circuit</em> in a telecom system.</p>

 <p>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.</p>

 <p>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.</p>


           <hr/>

           <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="/security.html">Security</a></li>
             <li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
           </ul>

           <p id="-legal">
             Apache Qpid, Messaging built on AMQP; Copyright &#169; 2015
             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>
     </div>
   </body>
 </html>
	<!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>Dispatch Addressing - Apache Qpid™</title>
	<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
	<link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
	<script type="text/javascript">var _deferredFunctions = [];</script>
	<script type="text/javascript" src="/deferred.js" defer="defer"></script>
	<!--[if lte IE 8]>
	<link rel="stylesheet" href="/ie.css" type="text/css"/>
	<script type="text/javascript" src="/html5shiv.js"></script>
	<![endif]-->

	<!-- Redirects for `go get` and godoc.org -->
	<meta name="go-import"
	content="qpid.apache.org git https://gitbox.apache.org/repos/asf/qpid-proton.git"/>
	<meta name="go-source"
	content="qpid.apache.org
	https://github.com/apache/qpid-proton/blob/go1/README.md
	https://github.com/apache/qpid-proton/tree/go1{/dir}
	https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
	</head>
	<body>
	<div id="-content">
	<div id="-top" class="panel">
	<a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>

	<a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>

	<ul id="-global-navigation">
	<li><a id="-logotype" href="/index.html">Apache Qpid<sup>™</sup></a></li>
	<li><a href="/documentation.html">Documentation</a></li>
	<li><a href="/download.html">Download</a></li>
	<li><a href="/discussion.html">Discussion</a></li>
	</ul>
	</div>

	<div id="-menu" class="panel" style="display: none;">
	<div class="flex">
	<section>
	<h3>Project</h3>

	<ul>
	<li><a href="/overview.html">Overview</a></li>
	<li><a href="/components/index.html">Components</a></li>
	<li><a href="/releases/index.html">Releases</a></li>
	</ul>
	</section>

	<section>
	<h3>Messaging APIs</h3>

	<ul>
	<li><a href="/proton/index.html">Qpid Proton</a></li>
	<li><a href="/components/jms/index.html">Qpid JMS</a></li>
	<li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
	</ul>
	</section>

	<section>
	<h3>Servers and tools</h3>

	<ul>
	<li><a href="/components/broker-j/index.html">Broker-J</a></li>
	<li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
	<li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
	</ul>
	</section>

	<section>
	<h3>Resources</h3>

	<ul>
	<li><a href="/dashboard.html">Dashboard</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
	<li><a href="/resources.html">More resources</a></li>
	</ul>
	</section>
	</div>
	</div>

	<div id="-search" class="panel" style="display: none;">
	<form action="http://www.google.com/search" method="get">
	<input type="hidden" name="sitesearch" value="qpid.apache.org"/>
	<input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
	<button type="submit">Search</button>
	<a href="/search.html">More ways to search</a>
	</form>
	</div>

	<div id="-middle" class="panel">
	<ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/components/index.html">Components</a></li><li><a href="/components/dispatch-router/index.html">Dispatch Router</a></li><li>Dispatch Addressing</li></ul>

	<div id="-middle-content">
	<h1 id="dispatch-addressing">Dispatch Addressing</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 <code>to</code> and <code>reply-to</code>
	fields of a message's properties. They are also used during the creation of
	links in the <code>address</code> field of a <code>source</code> or a <code>target</code>.</p>

	<p>Addresses designate various kinds of entities in a messaging network:</p>

	<ul>
	<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:
	<ul>
	<li>Queues</li>
	<li>Durable Topics</li>
	<li>Exchanges</li>
	</ul></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>
	<li><em>Routing pattern</em> - direct, multicast, balanced</li>
	<li><em>Routing mechanism</em> - message routed, link routed</li>
	<li><em>Undeliverable action</em> - drop, hold and retry, redirect</li>
	<li><em>Reliability</em> - N destinations, etc.</li>
	</ul>

	<h2 id="routing-patterns">Routing patterns</h2>

	<p>Routing patterns constrain the paths that a message can take across a network.</p>

	<table>
	<thead>
	<tr>
	<th>Pattern</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<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>
	<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>
	<td><em>Balanced</em></td>
	<td>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.</td>
	</tr>
	</tbody>
	</table>

	<h2 id="routing-mechanisms">Routing mechanisms</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>
	<p>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.</p>
	</blockquote>

	<p>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.</p>

	<h3 id="message-routing">Message routing</h3>

	<p>Message routing occurs upon delivery of a message and is done based on the address
	in the message's <code>to</code> field.</p>

	<p>When a delivery arrives on an incoming message-routing link, the router extracts the
	address from the delivered message's <code>to</code> 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>
	<thead>
	<tr>
	<th>Delivery</th>
	<th>Handling</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<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>
	<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>

	<h3 id="link-routing">Link routing</h3>

	<p>Link routing occurs when a new link is attached to the router across one of its AMQP connections.
	It is done based on the <code>target.address</code> field of an inbound link and the <code>source.address</code> field
	of an outbound link.</p>

	<p>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 <em>virtual circuit</em> in a telecom system.</p>

	<p>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.</p>

	<p>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.</p>


	<hr/>

	<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="/security.html">Security</a></li>
	<li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
	</ul>

	<p id="-legal">
	Apache Qpid, Messaging built on AMQP; Copyright © 2015
	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>
	</div>
	</body>
	</html>