Chapter 23. Diverts
Diverts are objects configured in JBoss EAP messaging that help in diverting messages from one address to another. Diverts can be classified into the following types:
- Exclusive
- A message is only diverted to a new address and never sent to the old address.
- Non-exclusive
- A message is sent the old address, and a copy of it is also sent to the new address. Non-exclusive diverts can be used for splitting the flow of messages.
A divert will only divert a message to an address on the same server. If you want to divert to an address on a different server, a common pattern would be to divert to a local store-and-forward queue, then set up a bridge that consumes from that queue and forwards to an address on a different server.
Diverts are therefore a very sophisticated concept. When combined with bridges, diverts can be used to create interesting and complex routings. The set of diverts on a server can be thought of as a type of routing table for messages. Combining diverts with bridges allows you to create a distributed network of reliable routing connections between multiple geographically distributed servers, creating your global messaging mesh. See Configuring Core Bridges for more information on how to use bridges.
Diverts can be configured to apply a Transformer and an optional message filter. An optional message filter helps to divert only messages which match the specified filter. For more information on filters see Filter Expressions and Message Selectors.
A transformer is used for transforming messages to another form. When a transformer is specified, all diverted messages are transformed by the Transformer. All transformers must implement the org.apache.activemq.artemis.core.server.cluster.Transformer interface:
package org.apache.activemq.artemis.core.server.cluster;
import org.apache.activemq.artemis.core.server.ServerMessage;
public interface Transformer {
ServerMessage transform(ServerMessage message);
}
To enable JBoss EAP messaging to instantiate an instance of your transformer implementation, you must include it in a JBoss EAP module, and then add the module as an exported dependency to the org.apache.activemq.artemis module. See Create a Custom Module in the JBoss EAP Configuration Guide for information on how to create a custom module. To add a dependency to the org.apache.activemq.artemis module, open the file EAP_HOME/modules/system/layers/base/org/apache/activemq/artemis/main/module.xml in a text editor and add your <module> to the list of <dependencies> as in the following example.
<module xmlns="urn:jboss:module:1.3" name="org.apache.activemq.artemis">
<resources>
...
</resources>
<dependencies>
...
<module name="YOUR_MODULE_NAME" export="true"/>
</dependencies>
</module>23.1. Exclusive diverts
Below is in an example of an exclusive divert as it might appear in configuration:
<divert name="prices-divert" address="jms.topic.priceUpdates" forwarding-address="jms.queue.priceForwarding" filter="office='New York'" transformer-class-name="org.apache.activemq.artemis.jms.example.AddForwardingTimeTransformer" exclusive="true"/>
In this example, a divert called prices-divert is configured that will divert any messages sent to the address jms.topic.priceUpdates, which maps to any messages sent to a Jakarta Messaging topic called priceUpdates, to another local address jms.queue.priceForwarding, corresponding to a local Jakarta Messaging queue called priceForwarding
We also specify a message filter string so that only messages with the message property office with a value of New York will be diverted. All other messages will continue to be routed to the normal address. The filter string is optional, if not specified then all messages will be considered matched.
Note that a transformer class is specified. In this example the transformer simply adds a header that records the time the divert happened.
This example is actually diverting messages to a local store and forward queue, which is configured with a bridge that forwards the message to an address on another server. See Configuring Core Bridges for more details.
23.2. Non-exclusive diverts
Below is an example of a non-exclusive divert. Non exclusive diverts can be configured in the same way as exclusive diverts with an optional filter and transformer.
<divert name="order-divert" address="jms.queue.orders" forwarding-address="jms.topic.spytopic" exclusive="false"/>
The above divert takes a copy of every message sent to the address jms.queue.orders, which maps to a Jakarta Messaging queue called orders, and sends it to a local address called jms.topic.SpyTopic, corresponding to a Jakarta Messaging topic called SpyTopic.
Creating diverts
Use the management CLI to create the type of divert you want:
/subsystem=messaging-activemq/server=default/divert=my-divert:add(divert-address=news.in,forwarding-address=news.forward)
Non-exclusive diverts are created by default. To create an exclusive divert use the exclusive attribute:
/subsystem=messaging-activemq/server=default/divert=my-exclusive-divert:add(divert-address=news.in,forwarding-address=news.forward,exclusive=true)
The below table captures a divert’s attributes and their description. You can have the management CLI display this information using the following command:
/subsystem=messaging-activemq/server=default/divert=*:read-resource-description()
| Attribute | Description |
|---|---|
| divert-address | Address to divert from. Required. |
| exclusive | Whether the divert is exclusive, meaning that the message is diverted to the new address, and does not go to the old address at all. The default is false. |
| filter | An optional filter string. If specified then only messages which match the filter expression will be diverted. |
| forwarding-address | Address to divert to. Required. |
| routing-name | Routing name of the divert. |
| transformer-class-name | The name of a class used to transform the message’s body or properties before it is diverted. |
