2.11. Message Redelivery
Overview
Messages are redelivered to a client when any of the following occurs:
- A transacted session is used and
rollback()is called. - A transacted session is closed before commit is called.
- A session is using
CLIENT_ACKNOWLEDGEandSession.recover()is called.
The policy used to control how messages are redelivered and when they are determined dead can be configured in a number of ways:
- On the broker, using the broker's redelivery plug-in,
- On the connection factory, using the connection URI,
- On the connection, using the
RedeliveryPolicy, - On destinations, using the connection's
RedeliveryPolicyMap.
Redelivery properties
The following table list the properties that control message redelivery.
| Option | Default | Description |
|---|---|---|
collisionAvoidanceFactor | 0.15 | Specifies the percentage of range of collision avoidance. |
maximumRedeliveries | 6 | Specifies the maximum number of times a message will be redelivered before it is considered a poisoned pill and returned to the broker so it can go to a dead letter queue. -1 specifies an infinite number of redeliveries. |
maximumRedeliveryDelay | -1 | Specifies the maximum delivery delay that will be applied if the useExponentialBackOff option is set. -1 specifies that no maximum be applied. |
initialRedeliveryDelay | 1000 | Specifies the initial redelivery delay in milliseconds. |
redeliveryDelay | 1000 | Specifies the delivery delay, in milliseconds. |
useCollisionAvoidance | false | Specifies if the redelivery policy uses collision avoidance. |
useExponentialBackOff | false | Specifies if the redelivery time out should be increased exponentially. |
backOffMultiplier | 5 | Specifies the back-off multiplier. |
Configuring the broker's redelivery plug-in
Configuring a broker's redelivery plug-in is a good way to tune the redelivery of messages to all of the consumer's that use the broker. When using the broker's redelivery plug-in, it is recommended that you disable redelivery on the consumer side (if necessary, by setting
maximumRedeliveries to 0 on the destination).
The broker's redelivery policy configuration is done through the
redeliveryPlugin element. As shown in the following example this element is a child of the broker's plugins element and contains a policy map defining the desired behavior.
Example 2.17. Configuring the Redelivery Plug-In
<broker xmlns="http://activemq.apache.org/schema/core" ... >
....
<plugins>
<redeliveryPlugin ... >
<redeliveryPolicyMap>
<redeliveryPolicyMap>
<redeliveryPolicyEntries> 1
<!-- a destination specific policy -->
<redeliveryPolicy queue="SpecialQueue"
maximumRedeliveries="3"
initialRedeliveryDelay="3000" />
</redeliveryPolicyEntries>
<!-- the fallback policy for all other destinations -->
<defaultEntry> 2
<redeliveryPolicy maximumRedeliveries="3"
initialRedeliveryDelay="3000" />
</defaultEntry>
</redeliveryPolicyMap>
</redeliveryPolicyMap>
</redeliveryPlugin>
</plugins>
...
</broker>- 1
- The
redeliveryPolicyEntrieselement contains a list ofredeliveryPolicyelements that configures redelivery policies on a per-destination basis. - 2
- The
defaultEntryelement contains a singleredeliveryPolicyelement that configures the redelivery policy used by all destinations that do not match the one with a specific policy.
Configuring the redelivery using the broker URI
Clients can specify their preferred redelivery by adding redelivery policy information as part of the connection URI used when getting the connection factory. The following example shows code for setting the maximum number of redeliveries to 4.
Example 2.18. Setting the Redelivery Policy using a Connection URI
ActiveMQConnectionFactory connectionFactory =
new ActiveMQConnectionFactory("tcp://localhost:61616?jms.redeliveryPolicy.maximumRedeliveries=4");
For more information on connection URIs see the Connection Reference.
Setting the redelivery policy on a connection
The
ActiveMQConnection class' getRedeliveryPolicy() method allows you to configure the redelivery policy for all consumer's using that connection.
getRedeliveryPolicy() returns a RedeliveryPolicy object that controls the redelivery policy for the connection. The RedeliveryPolicy object has setters for each of the properties listed in Table 2.3, “Redelivery Policy Options”.
The following example shows code for setting the maximum number of redeliveries to 4.
Example 2.19. Setting the Redelivery Policy for a Connection
ActiveMQConnection connection = connectionFactory.createConnetion(); // Get the redelivery policy RedeliveryPolicy policy = connection.getRedeliveryPolicy(); // Set the policy policy.setMaximumRedeliveries(4);
Setting the redelivery policy on a destination
For even more fine grained control of message redelivery, you can set the redelivery policy on a per-destination basis. The
ActiveMQConnection class' getRedeliveryPolicyMap() method returns a RedeliveryPolicyMap object that is a map of RedeliveryPolicy objects with destination names as the key.
Note
You can also specify destination names using wildcards.
Each
RedeliveryPolicy object controls the redelivery policy for all destinations whose name match the destination name specified in the map's key.
Note
If a destination does not match one of the entries in the map, the destination will use the redelivery policy set on the connection.
The following example shows code for specifying that messages in the queue
FRED.JOE can only be redelivered 4 times.
Example 2.20. Setting the Redelivery Policy for a Destination
ActiveMQConnection connection =
connectionFactory.createConnetion();
// Get the redelivery policy
RedeliveryPolicy policy = new RedeliveryPolicy();
policy.setMaximumRedeliveries(4);
//Get the policy map
RedeliveryPolicyMap map = connection.getRedeliveryPolicyMap();
map.put(new ActiveMQQueue("FRED.JOE"), queuePolicy);