diff options
Diffstat (limited to 'qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml')
| -rw-r--r-- | qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml | 210 |
1 files changed, 180 insertions, 30 deletions
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml index 1692fdc038..1018f95b04 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml @@ -22,34 +22,184 @@ <section id="Java-Broker-Concepts-Exchanges"> <title>Exchanges</title> -<para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtual Host</emphasis> which receives -messages from producers and routes them to matching message <emphasis>Queue</emphasis>s within the <emphasis>Virtual Host</emphasis>. -Message routing occurs based on the particular Exchange's routing algorithm and its configured queue <emphasis>Binding</emphasis>s.</para> -<para> -The following <emphasis>Exchange</emphasis> types are supported by the <emphasis>Broker</emphasis>: - <itemizedlist> - <listitem><para><emphasis>Direct</emphasis>: 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 - </para></listitem> - <listitem><para><emphasis>Topic</emphasis>: routes messages to queues based on heirarchical pattern matching between the routing - key for each message and the binding keys used to bind Queues to the Exchange. This exchange type is used to support the classic - publish/subscribe paradigm using a topic namespace as the addressing model to select and deliver messages across multiple - consumers based on a partial or full match on a topic pattern. - </para> - <para> - Binding and routing keys for this Exchange use a "." deliminator to seperate words representing different levels of the heirarchy, - with special meaning given to use of * and # as a word within a binding key such that a * matches any single word in a routing - key and # matches zero or more words, allowing a binding key to match many routing keys for published messages. For example, - a binding key of <emphasis>a.b.#</emphasis> would match the routing keys <emphasis>a.b</emphasis>, <emphasis>a.b.c</emphasis>, and - <emphasis>a.b.c.d</emphasis>, but not the routing key <emphasis>a.z</emphasis>.</para></listitem> - <listitem><para><emphasis>Fanout</emphasis>: routes messages to all queues bound to the exchange, regardless of the message's routing key. - </para></listitem> - <listitem><para><emphasis>Headers</emphasis>: routes messages to queues based on header properties within the AMQP message. - The message is passed to a queue if the header properties of the message satisfy header matching arguments table with which the queue was bound. - </para></listitem> - </itemizedlist> -</para> -<para>Also, Broker supports the concept of a Default Exchange to which all queues are bound using their name as a binding key.</para> -<para>Any number of exchanges of any type can be created on <emphasis>Virtual Host</emphasis>.</para> -<para>Exchange configuration is covered in <xref linkend="Java-Broker-Exchanges"/>.</para> + <para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtual Host</emphasis> which receives + messages from producers and routes them to matching <emphasis>Queue</emphasis>s within the <emphasis>Virtual Host</emphasis>.</para> + <para>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 <xref linkend="Java-Broker-Concepts-Exchanges-Types"/> below.</para> + <para>The server predeclares a number of exchange instances with names starting with "<literal>amq.</literal>". These are defined in + <xref linkend="Java-Broker-Concepts-Exchanges-Predeclared"/>.</para> + <para>Applications can make use the pre-declared exchanges, or they may declare their own. The number of exchanges within a virtual host is + limited only by resource constraints.</para> + <para>The behaviour when an exchange is unable to route a message to any queue is defined in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/></para> + <para>Exchange configuration is covered in <xref linkend="Java-Broker-Exchanges"/>.</para> + <section id="Java-Broker-Concepts-Exchanges-Predeclared"> + <title>Predeclared Exchanges</title> + <para>Each virtual host pre-declares the following exchanges: + <itemizedlist> + <listitem>amq.direct (an instance of a direct exchange)</listitem> + <listitem>amq.topic (an instance of a topic exchange)</listitem> + <listitem>amq.fanout (an instance of a fanout exchange)</listitem> + <listitem>amq.match (an instance of a headers exchange)</listitem> + </itemizedlist> + </para> + <para>The conceptual "<literal>default exchange</literal>" 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.</para> + <para>Applications may not declare exchanges with names beginning with "<literal>amq.</literal>". Such names are reserved for system use.</para> + </section> + <section id="Java-Broker-Concepts-Exchanges-Types"> + <title>Exchange Types</title> + <para> + The following Exchange types are supported. + <itemizedlist> + <listitem>Direct</listitem> + <listitem>Topic</listitem> + <listitem>Fanout</listitem> + <listitem>Headers</listitem> + </itemizedlist> + These exchange types are described in the following sub-sections.</para> + + <section id="Java-Broker-Concepts-Exchanges-Types-Direct"> + <title>Direct</title> + <para>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 <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> + binding argument specifying a JMS message selector</link>. + </para> + <para>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.</para> + <figure> + <title>Direct exchange</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Exchange-Direct.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </figure> + <para>The figure above illustrates the operation of direct exchange type. The yellow messages published with the routing key + "<literal>myqueue</literal>" match the binding key corresponding to queue "<literal>myqueue</literal>" and so are routed there. The red + messages published with the routing key "<literal>foo</literal>" match two bindings in the table so a copy of the message is + routed to both the "<literal>bar1</literal>" and "<literal>bar2</literal>" queues.</para> + <para>The routing key of the blue message matches no binding keys, so the message is unroutable. It is handled as described + in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> + </section> + <section id="Java-Broker-Concepts-Exchanges-Types-Topic"> + <title>Topic</title> + <para>This exchange type is used to support the classic publish/subscribe paradigm.</para> + <para>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.</para> + <para>Additional filter rules may be specified using a <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> + binding argument specifying a JMS message selector</link>.</para> + <para>The following three figures help explain how the topic exchange functions.</para> + <para></para> + <figure> + <title>Topic exchange - exact match on topic name</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Exchange-Topic.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </figure> + <para>The figure above illustrates publishing messages with routing key "<literal>weather</literal>". The exchange routes each + message to every bound queue whose binding key matches the routing key.</para> + <para>In the case illustrated, this means that each subscriber's queue receives every yellow message.</para> + <figure> + <title>Topic exchange - matching on hierarchical topic patterns</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Exchange-Topic-Hierarchical.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </figure> + <para>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.</para> + <para>In the case illustrated, <literal>sub1</literal> has received the red and green message as "<literal>news.uk</literal>" and "<literal>news.de</literal>" + match binding key "<literal>news.#</literal>". The red message has also gone to <literal>sub2</literal> and <literal>sub3</literal> as it's routing key + is matched exactly by "<literal>news.uk</literal>" and by "<literal>*.uk</literal>".</para> + <para>The routing key of the yellow message matches no binding keys, so the message is unroutable. It is handled as described + in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> + <figure> + <title>Topic exchange - matching on JMS message selector</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Exchange-Topic-JMSSelector.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </figure> + <para>The figure above illustrates messages with properties published with routing key "<literal>shipping</literal>".</para> + <para>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.</para> + <para>In the case illustrated, <literal>sub1</literal> has received the yellow and blue message as their property "<literal>area</literal>" + cause expression "<literal>area in ('Forties', 'Cromarty')</literal>" to evaluate true. Similarly, the yellow message has also gone to + <literal>gale_alert</literal> as its property "<literal>speed</literal>" causes expression "<literal>speed > 7 and speed < 10</literal>" + to evaluate true.</para> + <para>The properties of purple message cause no expressions to evaluate true, so the message is unroutable. It is handled as described in + <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> + </section> + <section id="Java-Broker-Concepts-Exchanges-Types-Fanout"> + <title>Fanout</title> + <para>The fanout exchange type routes messages to all queues bound to the exchange, regardless of the message's routing key.</para> + <para>Filter rules may be specified using a <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> + binding argument specifying a JMS message selector</link>.</para> + <figure> + <title>Fanout exchange</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Exchange-Fanout.png" format="PNG" scalefit="1"/> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="Java-Broker-Concepts-Exchanges-Types-Headers"> + <title>Headers</title> + <para>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 <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-x-match"> + x-match expression</link> specified by the binding arguments with which the queue was bound. + </para> + </section> + </section> + <section id="Java-Broker-Concepts-Exchanges-BindingArguments"> + <title>Binding Arguments</title> + <para>Binding arguments are used by certain exchange types to further filter messages.</para> + <section id="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> + <title>JMS Selector</title> + <para>The binding argument <literal>x-filter-jms-selector</literal> 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.<footnote><para> + This is a Qpid specific extension.</para></footnote>.</para> + </section> + <section id="Java-Broker-Concepts-Exchanges-BindingArguments-x-match"> + <title>x-match</title> + <para>The binding argument <literal>x-match</literal> is understood by exchange type headers. It can take two values, dictating how the + rest of the name value pairs are treated during matching.</para> + <itemizedlist> + <listitem><literal>all</literal> 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)</listitem> + <listitem>any<literal></literal> 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)</listitem> + </itemizedlist> + <para>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.</para> + </section> + </section> + <section id="Java-Broker-Concepts-Exchanges-UnroutableMessage"> + <title>Unrouteable Messages</title> + <para>If an exchange is unable to route a message to any queues, the Broker will: + <itemizedlist> + <listitem>If using 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 messages is still unroutable, + the message is discarded.</listitem> + <listitem>If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the<link linkend="Java-Broker-Close-Connection-When-No-Route"> + close when no route</link> feature did not close the connection, the message is returned to the Producer.</listitem> + <listitem>Otherwise, the message is discarded.</listitem> + </itemizedlist> + </para> + </section> </section> |