Rollback Exception Strategy

You can define a rollback exception strategy to ensure that a message that throws an exception in a flow is rolled back for reprocessing. Use a rollback exception strategy when you cannot correct an error when it it occurs in a flow. Usually, you use a rollback exception strategy to handle errors that occur in a flow that involves a transaction. If the transaction fails — that is, if a message throws an exception while being processed — then the rollback exception strategy rolls back transactions where they exist in the flow. If the inbound endpoint is transactional, Mule delivers the message to the inbound endpoint of the parent flow again to reattempt processing (i.e. message redelivery).

Beyond managing transactional errors, you can use a rollback exception strategy to:

• manage unhandled exceptions (i.e. exceptions which the application fails to catch)
• flows in which messages require redelivery

A rollback exception strategy has the potential to introduce an infinite loop of activity within a flow: a message throws an error, the rollback exception strategy catches the exception and rolls the message back for reprocessing; the message throws an error again, the rollback exception strategy catches the exception again and rolls the message back for reprocessing, and so on.

To avoid this infinite loop and responsibly manage unresolvable errors, you can apply two limitations to a rollback exception strategy:

• define the maximum number of times that the rollback exception strategy will attempt to redeliver the message for processing
• define a flow to handle those messages which exceed the maximum number of redelivery attempts

Use Rollback Exception Strategy for Transactions

Unlike a catch exception strategy which always commits a failed transaction and consumes the message, a rollback exception strategy gives a message a few attempts to move through the flow successfully before committing a failed transaction and consuming the message.

For example, suppose you have a flow that involves a bank transaction to deposit funds into an account. You configure a rollback exception strategy to handle errors that occur in this flow; when an error occurs during processing — say, a flow-external bank account database is temporarily unavailable — the message throws an exception. The rollback exception strategy catches the exception, and rolls the message back to the beginning of the flow to reattempt processing. During the second attempt at processing, the database is online again and the message successfully reaches the end of the flow.

Mule attempts message redelivery when your flow uses one of the following two types of transports: transactional or reliable.

• A transactional transport consumes a message as it travels through the flow, transforming it to a different object, for example, or enriching it with more data. When a message using a transactional transport throws an exception, a rollback exception strategy rolls back the transaction so the transport can return a message to its original state for reprocessing.

• A reliable transport does not consume a message as it travels through the flow until it can ascertain that the message has successfully reached the end of the flow.When a message using a reliable transport throws an exception, the rollback exception strategy discards the partially processed message and instructs the flow to attempt processing the original message again.

If your flow involves a reliable transport and a rollback exception strategy, you must set the flow’s Processing Strategy to “synchronous”. (Configure the Processing Strategy in the Flow Properties panel.) This is because reliable transports do not consume messages, they wait for messages to successfully complete a flow before consuming it; therefore, the flow must process synchronously. If you deploy a Mule application that contains a flow with an asynchronous processing strategy and a rollback exception strategy configured for message redelivery, the application will fail!

Use Rollback Exception Strategy for Unhandled Exceptions

At times, message processors in a flow encounter exceptions which they are unable to resolve by performing corrective measures; these types of errors are called "unhanded exceptions." Typically, all unhanded exceptions are handled by Mule's default exception strategy, but you can customize a rollback exception strategy to more efficiently route messages with unhandled exceptions.

Depending on the flow exchange pattern, a rollback exception strategy routes messages with unhanded exceptions in one of two ways:

• When the flow exchange pattern is one-way, the rollback exception strategy instructs the inbound endpoint transport to execute corrective actions.
• When the flow exchange pattern is request-response, rollback exception strategy changes the payload of a message and returns it to the client.

Rollback Exception Strategy vs. Default Exception Strategy

Where once you would have used Mule's default exception strategy to process unhanded exceptions, you can now configure the much improved rollback exception strategy to do so. To demonstrate the advantages rollback exceptions strategy has to offer, it is worthwhile noting some key differences in the methods each strategy employs when routing messages with unhanded exceptions.

Default Exception Strategy:

• stores the exception information in the payload of the message
• returns null in the exceptionPayload attributeMessage
• injects NullPayload as the message's payload; unable to customize
• records exception information in the exceptionPayload attribute; unable to customize

Rollback Exception Strategy:

• retains the information in the message payload at the time the exception was thrown; does not alter the message payload
• stores the exception information in the exceptionPayload
• returns the message processing result during execution of the exception strategy
• records exception information in the exceptionPayload attribute; able to customize

Where the default exception strategy faltered, rollback exception strategy performs. Using a rollback exception strategy, you can send messages with unhanded exceptions to a dead letter queue, send failure notifications, and change the result of a flow's execution.

Configuring a Rollback Exception Strategy

Whether your flow involves transactional or reliable transports, you can configure its rollback exception strategy in Mule Studio as follows:

1. From the Error Handling palette group, drag and drop the Rollback Exception Strategy icon into the footer bar of a flow.
   
   
2. Double-click the configuration icon in the Rollback Exception Strategy box that appears.
3. In the Rollback Exception Strategy Properties panel that appears, enter a name for your rollback exception strategy in the Display Name field.
   
   
   
   
4. Click the Enable Notifications checkbox to instruct Mule to send an exception notification to a registered listener — for example, the Mule Management Console — whenever a message throws an exception in this flow.

5. Enter a number in the Max redelivery attempts field to define the number of times you want the rollback exception strategy to rollback a message for reprocessing. Note that the default value is set to 0, which means the rollback exception strategy will not attempt to redeliver the message and will throw a MessageRedeliveredException upon the first processing failure.

   If you enter nothing in the Max redelivery attempts field (i.e. leave the field blank), the rollback exception strategy will redeliver the message over and over again, creating an infinite loop. Refer to Configuring Redelivery Attempts in JMS Global Connector below to learn more about setting this value to 0.

6. Enter an exception type in the When field to indicate the kind of exception the rollback exception should handle.

   Expression defined?	Exception Strategy Behavior
   no	All messages in this flow that throw exceptions will be handled by this rollback exception strategy.
   yes	When Mule evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy. For example, if you enter #[exception.causedBy(org.mule.example.AlreadyProcessedException)], only those messages which throw an org.mule.example.AlreadyProcessedException exception will be handled by this exception strategy. Mule’s default exception strategy implicitly handles all exceptions which do not match the expression you have defined.

   What follows are some examples of expressions that you can enter in the When field: #[exception.causedBy(org.mule.example.ExceptionType)] #[exception.causedExactlyBy(org.mule.example.ExceptionType)] #[exception.causeMatches(org.mule.example.*)] #[exception.causeMatches(*) and !exception.causedBy(java.lang.ArithmeticException) and !exception.causedBy(org.mule.api.registry.ResolverException)]

7. Click the Documentation tab and record information about the rollback exception strategy, if you wish, then click OK to save your changes.

8. Drag building blocks from the palette into the Rollback Exception Strategy box to build a flow that processes messages that throw exceptions in the parent flow. A rollback exception strategy can contain any number of message processors.

   If your flow uses a reliable transport, you can stop at this point and now configure a redelivery exhausted sub flow. If you choose not to configure a redelivery exhausted sub flow: a message that exceeds its redelivery attempts (a.k.a. “a poisoned message”) throws a MessageRedeliveredException, the exception strategy commits the transaction, and, the exception strategy consumes the message.

9. Click the arrow to expand the redelivery exhausted pane appended to the bottom of the rollback exception strategy box.
10. Drag building blocks from the palette into the redelivery exhausted box to build a flow that processes messages which exceed the maximum number of redelivery attempts. For example, you may wish to use redelivery exhausted to direct all “poisoned messages” to a dead letter queue. A redelivery exhausted flow can contain any number of message processors.

You can define only one exception strategy for each flow. If you need to design a more complex error handling strategy that involves more than one way of handling exceptions, consider using a Choice Exception Strategy.

Configuring Redelivery Attempts in JMS Global Connector

Mule creates a digest of a message’s payload in order to generate a redelivery attempt ID. Mule uses this unique ID as part of its redelivery policy which keeps track of the number of message redelivery attempts. (To generate a digest, Mule applies a hash function to the message to obtain a fixed-size bit string that is unique to the message.)

You can use a JMS global connector's redelivery policy to improve the performance of a flow that processes very large or streaming message payloads. Rather than generating a unique ID from a message's (potentially large or streaming) payload, a JMS global connector uses its JMSRedelivery property to keep track of message redelivery attempts.

If your flow uses a JMS global connector, you can configure it to manage the redelivery policy by defining its Max Redelivery.

1. Click the Global Elements tab.
2. Double-click your JMS Global Connector to open the Global Element Properties panel, and click the Advanced tab.
3. Enter a number in the Max Redelivery field to define the number of times you want the rollback exception strategy to rollback a message for reprocessing, and click OK to save your changes. Note that the default value of this field is set to -1; this ensures that the JMS global connector’s redelivery policy defers to your rollback exception strategy’s redelivery policy by default.
   
   
   
   
4. Click the Message Flow tab and double-click the configuration icon in the header of your rollback exception strategy.

5. In the Rollback Exception Strategy Properties panel that appears, enter a “0” in the Max redelivery attempts field and click OK to save your changes.

   If your flow uses a JMS global connector and you do not want the connector to manage your rollback strategy’s redelivery policy, then be sure to set the connector’s Max Redelivery field to -1. This ensures that the JMS global connector’s redelivery policy defers to your rollback exception strategy’s redelivery policy by default.

   Rollback Exception Strategy configured in flow?	Max Redelivery Set in Rollback ES Properties	Max Redelivery Set in JMS Global Connector	Redelivery Exhausted Configured?	Result
   yes	3	-1	yes	Rollback exception strategy redelivers the message to parent flow 3 times. After 3 failures, message throws a MessageRedeliveredException. Rollback exception strategy routes message to redelivery exhausted for processing before committing the transaction and consuming the message.
   yes	3	-1	no	Rollback exception strategy redelivers the message to parent flow 3 times. After 3 failures, message throws a MessageRedeliveredException. Rollback exception strategy commits the transaction and consumes the message.
   yes	0	-1	no	Rollback exception strategy redelivers the message over and over again, creating an infinite loop.
   yes	0	-1	yes	Rollback exception strategy redelivers the message over and over again, creating an infinite loop.
   yes	0	4	yes	Rollback exception strategy redelivers the message to parent flow 4 times, as per the JMS global connector redelivery policy. After 4 failures, message throws a MessageRedeliveredException. Rollback exception strategy routes message to redelivery exhausted for processing before committing the transaction and consuming the message.

Creating a Global Rollback Exception Strategy

You can create one or more global exception strategies to reuse in flows throughout your entire Mule application. First, create a global rollback exception strategy, then add a Reference Exception Strategy to a flow to apply the error handling behavior of your new global rollback exception strategy.

1. Click the Global Elements tab below the canvas.
2. Click the Create button and in the Choose Global Type panel that appears, click Error Handling to expand the list of exceptions strategies, select Rollack Exception Strategy and then click OK.
   
   
   
   
3. Follow steps 3 – 7 above to configure your global rollback exception strategy.
4. Click the Message Flow tab below the canvas. On the Message Flow canvas, note that your newly created global rollback exception strategy box appears outside the parent flow. Because it is global, your new rollback exception strategy exists independently of any Mule flow.
   
   

5. Follow steps 8 - 10 above to build your global rollback exception strategy and redelivery exhausted flow.

   If you have configured more than one flow in your Mule application, click the flow tab of another flow to view its canvas: note that your new global exception strategy box appears outside the parent flow on each flow’s canvas. You can edit the message processors inside your global exception strategy on the canvas of any flow.

Applying a Global Rollback Exception Strategy to a Flow

Use a reference exception strategy to instruct a flow to employ the error handling behavior defined by your global rollback exception strategy. In other words, you must ask your flow to refer to the global rollback exception strategy for instructions on how to handle errors.

1. From the Error Handling palette group, drag and drop the Reference Exception Strategy icon into the footer bar of a flow.
   
   
   
   
2. Double-click the Reference Exception Strategy icon on the footer bar to open the Pattern Properties panel.
   
   
   
   
3. Select your Global Exception Strategy from the drop-down combo box.
4. Click the Documentation tab and record information about the reference exception strategy, if you wish, then click OK to save your changes.

You can append a Reference Exception Strategy to any number of flows in your Mule application and instruct them to refer to any of the global catch, rollback or choice exception strategies you have created. You can direct any number of reference exception strategies to refer to the same global exception strategy.

You can create a global rollback exception strategy (i.e. access the Choose Global Type panel) from the reference exception strategy’s pattern properties panel. Click the + button next to the Global Exception Strategy drop-down combo box and follow the steps above to create a global choice exception strategy.