<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">4.6.&#160;Exchanges</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="Java-Broker-Concepts-Virtualhosts.html">Prev</a>&#160;</td><th align="center" width="60%">Chapter&#160;4.&#160;Concepts</th><td align="right" width="20%">&#160;<a accesskey="n" href="Java-Broker-Concepts-Queues.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Java-Broker-Concepts-Exchanges"></a>4.6.&#160;Exchanges</h2></div></div></div><p>An <span class="emphasis"><em>Exchange</em></span> is a named entity within the <span class="emphasis"><em>Virtualhost</em></span> which receives
  messages from producers and routes them to matching <span class="emphasis"><em>Queue</em></span>s within the <span class="emphasis"><em>Virtualhost</em></span>.</p><p>The server provides a set of exchange types with each exchange type implementing a different routing algorithm. For details of how
  these exchanges types work see <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-Types" title="4.6.2.&#160;Exchange Types">Section&#160;4.6.2, &#8220;Exchange Types&#8221;</a> below.</p><p>The server predeclares a number of exchange instances with names starting with "<code class="literal">amq.</code>". These are defined in
  <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-Predeclared" title="4.6.1.&#160;Predeclared Exchanges">Section&#160;4.6.1, &#8220;Predeclared Exchanges&#8221;</a>.</p><p>Applications can make use of the pre-declared exchanges, or they may declare their own. The number of exchanges within a <span class="emphasis"><em>Virtualhost</em></span> is
  limited only by resource constraints.</p><p>The behaviour when an <span class="emphasis"><em>Exchange</em></span> is unable to route a message to any queue is defined in <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" title="4.6.4.&#160;Unrouteable Messages">Section&#160;4.6.4, &#8220;Unrouteable Messages&#8221;</a></p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Concepts-Exchanges-Predeclared"></a>4.6.1.&#160;Predeclared Exchanges</h3></div></div></div><p>Each <span class="emphasis"><em>Virtualhost</em></span> pre-declares the following exchanges:
   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>amq.direct (an instance of a direct exchange)</p></li><li class="listitem"><p>amq.topic (an instance of a topic exchange)</p></li><li class="listitem"><p>amq.fanout (an instance of a fanout exchange)</p></li><li class="listitem"><p>amq.match (an instance of a headers exchange)</p></li></ul></div><p>
  </p><p>The conceptual "<code class="literal">default exchange</code>" always exists, effectively a special instance of
   direct exchange which uses the empty string as its name. All queues are automatically bound to it upon their creation
   using the queue name as the binding key, and unbound upon their deletion. It is not possible to manually add or remove
   bindings within this exchange.</p><p>Applications may not declare exchanges with names beginning with "<code class="literal">amq.</code>". Such names are reserved for system use.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Concepts-Exchanges-Types"></a>4.6.2.&#160;Exchange Types</h3></div></div></div><p>
   The following Exchange types are supported.
   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Direct</p></li><li class="listitem"><p>Topic</p></li><li class="listitem"><p>Fanout</p></li><li class="listitem"><p>Headers</p></li></ul></div><p>
   These exchange types are described in the following sub-sections.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-Types-Direct"></a>4.6.2.1.&#160;Direct</h4></div></div></div><p>The direct exchange type routes messages to queues based on an exact match between
    the routing key of the message, and the binding key used to bind the queue to the exchange. Additional
    filter rules may be specified using a <a class="link" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector" title="4.6.3.1.&#160;JMS Selector">
    binding argument specifying a JMS message selector</a>.
   </p><p>This exchange type is often used to implement point to point messaging. When used in this manner, the normal
   convention is that the binding key matches the name of the queue. It is also possible to use this exchange type
   for multi-cast, in this case the same binding key is associated with many queues.</p><div class="figure"><a id="d0e619"></a><p class="title"><strong>Figure&#160;4.4.&#160;Direct exchange</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Direct exchange" src="images/Exchange-Direct.png" /></div></div></div><br class="figure-break" /><p>The figure above illustrates the operation of direct exchange type. The yellow messages published with the routing key
    "<code class="literal">myqueue</code>" match the binding key corresponding to queue "<code class="literal">myqueue</code>" and so are routed there.  The red
    messages published with the routing key "<code class="literal">foo</code>" match two bindings in the table so a copy of the message is
    routed to both the "<code class="literal">bar1</code>" and "<code class="literal">bar2</code>" queues.</p><p>The routing key of the blue message matches no binding keys, so the message is unroutable. It is handled as described
     in <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" title="4.6.4.&#160;Unrouteable Messages">Section&#160;4.6.4, &#8220;Unrouteable Messages&#8221;</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-Types-Topic"></a>4.6.2.2.&#160;Topic</h4></div></div></div><p>This exchange type is used to support the classic publish/subscribe paradigm.</p><p>The topic exchange is capable of routing messages to queues based on wildcard matches between the routing key and the
     binding key pattern defined by the queue binding. Routing keys are formed from one or more words, with each word delimited
     by a full-stop (.). The pattern matching characters are the * and # symbols. The * symbol matches a single word  and the #
     symbol matches zero or more words.</p><p>Additional filter rules may be specified using a <a class="link" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector" title="4.6.3.1.&#160;JMS Selector">
     binding argument specifying a JMS message selector</a>.</p><p>The following three figures help explain how the topic exchange functions.</p><p /><div class="figure"><a id="d0e661"></a><p class="title"><strong>Figure&#160;4.5.&#160;Topic exchange - exact match on topic name</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Topic exchange - exact match on topic name" src="images/Exchange-Topic.png" /></div></div></div><br class="figure-break" /><p>The figure above illustrates publishing messages with routing key "<code class="literal">weather</code>". The exchange routes each
    message to every bound queue whose binding key matches the routing key.</p><p>In the case illustrated, this means that each subscriber's queue receives every yellow message.</p><div class="figure"><a id="d0e674"></a><p class="title"><strong>Figure&#160;4.6.&#160;Topic exchange - matching on hierarchical topic patterns</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Topic exchange - matching on hierarchical topic patterns" src="images/Exchange-Topic-Hierarchical.png" /></div></div></div><br class="figure-break" /><p>The figure above illustrates publishing messages with hierarchical routing keys. As before, the exchange routes each
    message to every bound queue whose binding key matches the routing key but as the binding keys contain wildcards, the
    wildcard rules described above apply.</p><p>In the case illustrated, <code class="literal">sub1</code> has received the red and green message as "<code class="literal">news.uk</code>" and "<code class="literal">news.de</code>"
    match binding key "<code class="literal">news.#</code>". The red message has also gone to <code class="literal">sub2</code> and <code class="literal">sub3</code> as it's routing key
    is matched exactly by "<code class="literal">news.uk</code>" and by "<code class="literal">*.uk</code>".</p><p>The routing key of the yellow message matches no binding keys, so the message is unroutable. It is handled as described
    in <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" title="4.6.4.&#160;Unrouteable Messages">Section&#160;4.6.4, &#8220;Unrouteable Messages&#8221;</a>.</p><div class="figure"><a id="d0e712"></a><p class="title"><strong>Figure&#160;4.7.&#160;Topic exchange - matching on JMS message selector</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Topic exchange - matching on JMS message selector" src="images/Exchange-Topic-JMSSelector.png" /></div></div></div><br class="figure-break" /><p>The figure above illustrates messages with properties published with routing key "<code class="literal">shipping</code>".</p><p>As before, the exchange routes each message to every bound queue whose binding key matches the routing key but as a JMS selector
    argument has been specified, the expression is evaluated against each matching message. Only messages whose message header values or properties
    match the expression are routed to the queue.</p><p>In the case illustrated, <code class="literal">sub1</code> has received the yellow and blue message as their property "<code class="literal">area</code>"
    cause expression "<code class="literal">area in ('Forties', 'Cromarty')</code>" to evaluate true.  Similarly, the yellow message has also gone to
    <code class="literal">gale_alert</code> as its property "<code class="literal">speed</code>" causes expression "<code class="literal">speed &gt; 7 and speed &lt; 10</code>"
    to evaluate true.</p><p>The properties of purple message cause no expressions to evaluate true, so the message is unroutable. It is handled as described in
    <a class="xref" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" title="4.6.4.&#160;Unrouteable Messages">Section&#160;4.6.4, &#8220;Unrouteable Messages&#8221;</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-Types-Fanout"></a>4.6.2.3.&#160;Fanout</h4></div></div></div><p>The fanout exchange type routes messages to all queues bound to the exchange, regardless of the message's routing key.</p><p>Filter rules may be specified using a <a class="link" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector" title="4.6.3.1.&#160;JMS Selector">
    binding argument specifying a JMS message selector</a>.</p><div class="figure"><a id="d0e759"></a><p class="title"><strong>Figure&#160;4.8.&#160;Fanout exchange</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Fanout exchange" src="images/Exchange-Fanout.png" /></div></div></div><br class="figure-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-Types-Headers"></a>4.6.2.4.&#160;Headers</h4></div></div></div><p>The headers exchange type routes messages to queues based on header properties within the message. The message is passed to
     a queue if the header properties of the message satisfy the <a class="link" href="Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-BindingArguments-x-match" title="4.6.3.2.&#160;x-match">
     x-match expression</a> specified by the binding arguments with which the queue was bound.
   </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Concepts-Exchanges-BindingArguments"></a>4.6.3.&#160;Binding Arguments</h3></div></div></div><p>Binding arguments are used by certain exchange types to further filter messages.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"></a>4.6.3.1.&#160;JMS Selector</h4></div></div></div><p>The binding argument <code class="literal">x-filter-jms-selector</code> specifies a JMS selector conditional expression. The expression
    is written in terms of message header and message property names.  If the expression evaluates to true, the message is routed to the queue.
    This type of binding argument is understood by exchange types direct, topic and fanout.<a class="footnote" href="#ftn.d0e786" id="d0e786"><sup class="footnote">[5]</sup></a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="Java-Broker-Concepts-Exchanges-BindingArguments-x-match"></a>4.6.3.2.&#160;x-match</h4></div></div></div><p>The binding argument <code class="literal">x-match</code> is understood by exchange type headers.  It can take two values, dictating how the
    rest of the name value pairs are treated during matching.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="literal">all</code> implies that all the other pairs must match the headers property of a message for that message to be routed
      (i.e. an AND match)</p></li><li class="listitem"><p><code class="literal">any</code> implies that the message should be routed if any of the fields in the headers property match one of the
      fields in the arguments table (i.e. an OR match)</p></li></ul></div><p>A field in the bind arguments matches a field in the message if either the field in the bind arguments has no value and a field of the
    same name is present in the message headers or if the field in the bind arguments has a value and a field of the same name exists in the
    message headers and has that same value.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Concepts-Exchanges-UnroutableMessage"></a>4.6.4.&#160;Unrouteable Messages</h3></div></div></div><p>If an exchange is unable to route a message to any queues, the Broker will:
   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If using the AMQP 1.0 protocol, and an alternate exchange has been set on the exchange, the message is routed to the alternate exchange.
     The alternate exchange routes the message according to its routing algorithm and its binding table.  If the message is still unroutable,
     the message is discarded unless the sending link has requested the <code class="literal">REJECT_UNROUTABLE</code> target capability, or the Exchange has its
     <code class="literal">unroutableMessageBehaviour</code> attribute set to <code class="literal">REJECT</code>.</p></li><li class="listitem"><p>If using the AMQP 0-10 protocol, and an alternate exchange has been set on the exchange, the message is routed to the alternate exchange.
    The alternate exchange routes the message according to its routing algorithm and its binding table.  If the message is still unroutable,
    the message is discarded.</p></li><li class="listitem"><p>If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the<a class="link" href="Java-Broker-Runtime-Close-Connection-When-No-Route.html" title="9.5.&#160;Closing client connections on unroutable mandatory messages">
     close when no route</a> feature did not close the connection, the message is returned to the Producer.</p></li><li class="listitem"><p>Otherwise, the message is discarded.</p></li></ul></div><p>
  </p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div class="footnote" id="ftn.d0e786"><p><a class="para" href="#d0e786"><sup class="para">[5] </sup></a>
    This is a Qpid specific extension.</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="Java-Broker-Concepts-Virtualhosts.html">Prev</a>&#160;</td><td align="center" width="20%"><a accesskey="u" href="Java-Broker-Concepts.html">Up</a></td><td align="right" width="40%">&#160;<a accesskey="n" href="Java-Broker-Concepts-Queues.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">4.5.&#160;Virtualhosts&#160;</td><td align="center" width="20%"><a accesskey="h" href="AMQP-Messaging-Broker-Java-Book.html">Home</a></td><td align="right" valign="top" width="40%">&#160;4.7.&#160;Queues</td></tr></table></div></div>