Composite Queues

Overview

Sometimes it is required by sending messages to one queue to forward them also to other queues and/or topics, for example for archiving or monitoring purposes. Or to automatically route messages to different queues based on static selectors. This can be done with composite queues.

Composite queues are virtual queues with mappings (called "binding") to collections of other queues and/or topics. Messages sent to a composite queue are copied to all bindings of this composite queue.

Composite queues are for producers only. It is not possible to create a consumer on them (but on any binding, of course).

Composite queues were introduced with SwiftMQ 7.4.0.

Configuration

The name of the composite queue is the queue name. This is automatically registered in JNDI as with any other queue. A composite queue entry can have queue and topic bindings. Both are optional. Each message sent to the composite queue are copied to all defined queue and topic bindings, except there is a message selector defined which does not match.

Both, queue and topic bindings, can be marked as a "default delivery". This is kind of an "else". If a message was not delivered to any other queue or topic binding, the message is delivered in a second step to all queue or topic bindings which are marked as "default delivery". Message selectors for those bindings have no effect. [since 9.4.0]

A queue binding points to another queue. This can be a physical queue, another composite queue, a clustered queue, a remote queue. The following attributes can be defined per queue binding:

Attribute Default Description
change-destination false If true, changes the JMS destination of message copies to the bindung queue.
default-delivery false If true, delivers the message to this binding if the message was not delivered to another non-default binding. Since 9.4.0.
generate-new-message-id false If true, generates a new message id for this binding's message copies.
message-selector null Optional selector to filter messages for this binding. This is only respected if "default-delivery" is false.

A topic binding points to a topic. The following attributes can be defined per topic binding:

Attribute Default Description
generate-new-message-id false If true, generates a new message id for this binding's message copies.
default-delivery false If true, delivers the message to this binding if the message was not delivered to another non-default binding. Since 9.4.0.
message-selector null Optional selector to filter messages for this binding. This is only respected if "default-delivery" is false.

The destination of message copies for topic bindings is always set to the binding topic.

Example: Archive

This example shows how messages sent to queue "orders" are automatically archived in queue "orders-archive":

      <composite-queues>
        <composite-queue name="orders-composite">
          <queue-bindings>
            <queue-binding name="orders"/>
            <queue-binding name="orders-archive"/>
          </queue-bindings>
          <topic-bindings/>
        </composite-queue>
      </composite-queues>

To automatically redirect JMS clients from "orders" to "orders-composite", just change the resp. JNDI alias:

      <alias name="orders" map-to="orders-composite@router1"/>

and let the client reconnect.

Example: Archive and Monitor

This example adds a topic binding to the composite queue which can be used to monitor the message flow on the composite queue:

      <composite-queues>
        <composite-queue name="orders-composite">
          <queue-bindings>
            <queue-binding name="orders"/>
            <queue-binding name="orders-archive"/>
          </queue-bindings>
          <topic-bindings>
            <topic-binding name="monitor.queue.orders"/>
          </topic-bindings>
        </composite-queue>
      </composite-queues>

Example: Selector based Message Routing

This example checks all messages sent to composite queue "orderinput" and routes them to different remote queues, based on selectors. The destination in the message will be set to the new destination queue name.

      <composite-queues>
        <composite-queue name="orderinput">
          <queue-bindings>
            <queue-binding name="orders@frankfurt" change-destination="true" message-selector="region = 'Europe'"/>
            <queue-binding name="orders@newyork" change-destination="true" message-selector="region = 'America'"/>
            <queue-binding name="orders@sidney" change-destination="true" message-selector="region = 'Australia'"/>
            <queue-binding name="orders@tokio" change-destination="true" message-selector="region = 'Asia'"/>
          </queue-bindings>
          <topic-bindings/>
        </composite-queue>
      </composite-queues>