Menu Search

4.6. Exchanges

An Exchange is a named entity within the Virtualhost which receives messages from producers and routes them to matching Queues within the Virtualhost.

When using AMQP 0-8, 0-9, 0-9-1, or 0-10, the exchange is the only way ingressing a message into the virtualhost. When using AMQP 1.0, the application may route messages using an exchange (to take advantage of exchange's routing behaviours), or it may route direcly to a queue (if point to point messaging is required).

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 Section 4.6.2, “Exchange Types” below.

The server predeclares a number of exchange instances with names starting with "amq.". These are defined in Section 4.6.1, “Predeclared Exchanges”.

Applications can make use of the pre-declared exchanges, or they may declare their own. The number of exchanges within a Virtualhost is limited only by resource constraints.

The behaviour when an Exchange is unable to route a message to any queue is defined in Section 4.6.4, “Unrouteable Messages”

4.6.1. Predeclared Exchanges

Each Virtualhost pre-declares the following exchanges:

  • amq.direct (an instance of a direct exchange)

  • amq.topic (an instance of a topic exchange)

  • amq.fanout (an instance of a fanout exchange)

  • amq.match (an instance of a headers exchange)

The conceptual "default exchange" 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.

Applications may not declare exchanges with names beginning with "amq.". Such names are reserved for system use.

4.6.2. Exchange Types

The following Exchange types are supported.

  • Direct

  • Topic

  • Fanout

  • Headers

These exchange types are described in the following sub-sections.

4.6.2.1. Direct

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 binding argument specifying a JMS message selector.

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.

Figure 4.4. Direct exchange

Direct exchange

The figure above illustrates the operation of direct exchange type. The yellow messages published with the routing key "myqueue" match the binding key corresponding to queue "myqueue" and so are routed there. The red messages published with the routing key "foo" match two bindings in the table so a copy of the message is routed to both the "bar1" and "bar2" queues.

The routing key of the blue message matches no binding keys, so the message is unroutable. It is handled as described in Section 4.6.4, “Unrouteable Messages”.

4.6.2.2. Topic

This exchange type is used to support the classic publish/subscribe paradigm.

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.

Additional filter rules may be specified using a binding argument specifying a JMS message selector.

The following three figures help explain how the topic exchange functions.

Figure 4.5. Topic exchange - exact match on topic name

Topic exchange - exact match on topic name

The figure above illustrates publishing messages with routing key "weather". The exchange routes each message to every bound queue whose binding key matches the routing key.

In the case illustrated, this means that each subscriber's queue receives every yellow message.

Figure 4.6. Topic exchange - matching on hierarchical topic patterns

Topic exchange - matching on hierarchical topic patterns

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.

In the case illustrated, sub1 has received the red and green message as "news.uk" and "news.de" match binding key "news.#". The red message has also gone to sub2 and sub3 as it's routing key is matched exactly by "news.uk" and by "*.uk".

The routing key of the yellow message matches no binding keys, so the message is unroutable. It is handled as described in Section 4.6.4, “Unrouteable Messages”.

Figure 4.7. Topic exchange - matching on JMS message selector

Topic exchange - matching on JMS message selector

The figure above illustrates messages with properties published with routing key "shipping".

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.

In the case illustrated, sub1 has received the yellow and blue message as their property "area" cause expression "area in ('Forties', 'Cromarty')" to evaluate true. Similarly, the yellow message has also gone to gale_alert as its property "speed" causes expression "speed > 7 and speed < 10" to evaluate true.

The properties of purple message cause no expressions to evaluate true, so the message is unroutable. It is handled as described in Section 4.6.4, “Unrouteable Messages”.

4.6.2.3. Fanout

The fanout exchange type routes messages to all queues bound to the exchange, regardless of the message's routing key.

Filter rules may be specified using a binding argument specifying a JMS message selector.

Figure 4.8. Fanout exchange

Fanout exchange

4.6.2.4. Headers

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 x-match expression specified by the binding arguments with which the queue was bound.

4.6.3. Binding Arguments

Binding arguments are used by certain exchange types to further filter messages.

4.6.3.1. JMS Selector

The binding argument x-filter-jms-selector 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.[4].

4.6.3.2. x-match

The binding argument x-match is understood by exchange type headers. It can take two values, dictating how the rest of the name value pairs are treated during matching.

  • all 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)

  • any 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)

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.

4.6.4. Unrouteable Messages

If an exchange is unable to route a message to any queues, the Broker will:

  • If using the AMQP 1.0 protocol, and an alternate binding has been set on the exchange, the message is routed to the alternate. If the message is still unroutable after considering the alternate binding, the message is discarded unless the sending link has requested the REJECT_UNROUTABLE target capability, or the Exchange has its unroutableMessageBehaviour attribute set to REJECT.

  • If using the AMQP 0-10 protocol, and an alternate binding has been set on the exchange, the message is routed to the alternate. If the message is still unroutable after considering the alternate binding,the message is discarded.

  • If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the close when no route feature did not close the connection, the message is returned to the Producer.

  • Otherwise, the message is discarded.



[4] This is a Qpid specific extension.