Chapter 33. Diverting and Splitting Message Flows

Diverts are objects that transparently divert messages routed to one address to some other address, without making any changes to any client application logic.
Diverts can be exclusive (messages are diverted to the new address and do not go to the previous address at all), or non-exclusive (a copy of the message is sent to the new address, and the original message goes to the old address). Non-exclusive diverts can therefore be used for splitting message flows, for example, when every order sent to an order queue must be monitored.
Diverts can also be configured with a filter, so that only messages that match the filter are diverted.
Diverts can also be configured to apply a Transformer. If specified, all diverted messages can be transformed by this Transformer.
Diverts only move messages to addresses on the same server, but when used in combination with bridges more complex routings can be set up. One common use case to "divert" to a different server is to divert messages to a local store-and-forward queue and then set up a bridge to consume from that queue and forward consumed messages to an address on another server. The diverts on a server can be thought of as a routing table for messages. Combining diverts with bridges allow you to create a distributed network of reliable routing connections between multiple geographically distributed servers.
Diverts are defined in the <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml file. There can be zero or more diverts in the file.

33.1. Exclusive Diverts

An exclusive divert diverts all matching messages that are routed to the old address to the new address. Matching messages do not get routed to the old address.
Diverts are defined in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml using the following directives: 
<divert name="prices-divert">                  
   <address>jms.topic.priceUpdates</address>
   <forwarding-address>jms.queue.priceForwarding</forwarding-address>    
   <filter string="office='New York'"/>
   <transformer-class-name>
    org.hornetq.jms.example.AddForwardingTimeTransformer
   </transformer-class-name>     
   <exclusive>true</exclusive>
</divert>
The prices-divert divert specified above diverts any messages sent to the address jms.topic.priceUpdates (a local JMS Topic called priceUpdates) to another local address jms.queue.priceForwarding (a local JMS Queue called priceForwarding).
A filter string is also specified so that only messages with the message property office='New York' are diverted. All other messages continue to be routed to their usual address. The filter string is optional; if it is not specified, all messages are diverted.
The transformer class is also optional. When specified, transformation is executed for each matching message. This allows you to change the message body or properties before the message is diverted. The example above uses a transformation to add a header recording the time the divert occurred.
As a whole, the above example diverts messages to a local store-and-forward queue, which is configured with a bridge, which forwards the message to an address on another HornetQ server.