Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.4)
  3. Developing
  4. Error Handling

  5. Rollback Exception Strategy

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 the transaction 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!
Transport Type When an exception occurs…​

VM

transactional

the message rolls back to its original state for reprocessing

JDBC

transactional

the message rolls back to its original state for reprocessing

JMS

transactional

the message rolls back to its original state for reprocessing

JMS

reliable

the session recovers (i.e. Mule discards the copy of the source file and attempts reprocessing the message using a fresh copy)

FTP

reliable

Mule discards the copy of the source file and attempts reprocessing the message using a fresh copy.

File

reliable

Mule discards the copy of the source file and attempts reprocessing the message using a fresh copy.

IMAP

reliable

Mule does not move the message from the mailbox and attempts reprocessing the message using a fresh copy of the original.

HTTP

reliable

Mule does not return an error message to the client and attempts reprocessing the message using a fresh copy of the original.

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 Visual Editor

  1. From the Error Handling palette group, drag and drop the Rollback Exception Strategy icon into the footer bar of a flow.

  2. Open the Rollback Exception Strategy’s Properties Editor, then configure the attributes according to the table below.

    add_to_flow
    Field Req’d Value

    Display Name

    x

    A unique name for the rollback exception strategy in your application.

    Max redelivery attempts

    x

    Enter an integer to define the number of times you want the rollback exception strategy to rollback a message for reprocessing. If you set the default value 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. =D===

    When

    Enter an expression to indicate the kind of exception the rollback exception should handle.
    • expression not defined: all messages in this flow that throw exceptions will be handled by this rollback exception strategy.
    • expression defined: when Mule evaluates the 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 are handled by this exception strategy. Mule’s default exception strategy implicitly handles all exceptions which do not match the expression you have defined in the When field.

    Enable Notifications

    true (default)

    false

    When set to true, instructs 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.

    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(*) && !exception.causedBy(java.lang.ArithmeticException) && !exception.causedBy(org.mule.api.registry.ResolverException)

  3. 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 not configure a redelivery exhausted sub flow. If you choose not to configure a redelivery exhausted sub flow:

    1. a message that exceeds its redelivery attempts (a.k.a. “a poisoned message”) throws a MessageRedeliveredException

    2. the exception strategy commits the transaction

    3. the exception strategy consumes the message

  4. 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.

XML Editor or Standalone

  1. In your flow, below all the message processors, add a rollback-exception-strategy element. Refer to code below.

  2. Configure attributes of the exception strategy according to the table below.

    Attribute Req’d Value

    doc:name

    x

    A unique name for the rollback exception strategy in your application.
    Not required in Standalone.

    maxRedeliveryAttempts

    x

    Use an integer to define the number of times you want the rollback exception strategy to rollback a message for reprocessing. If you set the default value 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. Refer to Configuring Redelivery Attempts in JMS Global Connector below to learn more about setting this value to 0.

    when

    Define an expression to indicate the kind of exception the rollback exception should handle. • expression not defined: all messages in this flow that throw exceptions will be handled by this rollback exception strategy. • expression defined: when Mule evaluates the 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 are handled by this exception strategy. Mule’s default exception strategy implicitly handles all exceptions which do not match the expression you have defined in the when attribute.

    enableNotifications

    true (default)

    false

    When set to true, Mule to send an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.

    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(*) &&

      • !exception.causedBy(java.lang.ArithmeticException) &&

      • !exception.causedBy(org.mule.api.registry.ResolverException)`

  3. Add child elements to your rollback-exception-strategy 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 not configure a redelivery exhausted sub flow. If you choose not to configure a redelivery exhausted sub flow:

    1. a message that exceeds its redelivery attempts (a.k.a. “a poisoned message”) throws a MessageRedeliveredException

    2. the exception strategy commits the transaction

    3. the exception strategy consumes the message

  4. Add an on-redelivery-attempts-exceeded child element to your rollback-exception-strategy element at the bottom, below all the message processors included in the exception strategy.

  5. Add child elements to your on-redelivery-attempts-exceeded child element 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.

STUDIO Visual Editor

  1. In the Global Elements tab, double-click to open the JMS Global Connector’s Global Element Properties panel, then click the Advanced tab.

  2. Enter an integer 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.

    max_redelivery_JMS

  3. Click the Message Flow tab, then double-click title bar of your rollback exception strategy.

  4. 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.

  5. Refer to the table below to learn more about entering a value in the maxDelivery fields.

XML Editor or Standalone

  1. To your global jms:connector element set above all the flows in your Mule project, add a maxRedelivery attribute and set the value to an integer to define the number of times you want the rollback exception strategy to rollback a message for reprocessing (see code below). Note that if you set the value of the attribute to -1, the JMS global connector’s redelivery policy defers to your rollback exception strategy’s redelivery policy by default.

    <jms:connector name="JMS" validateConnections="true" maxRedelivery="1" doc:name="JMS"/>

  2. To the rollback-exception-strategy element in your flow, set the value of the maxRedeliveryAttempts attribute to "0". Setting to "0" instructs Mule to use the value of maxRedelivery in the global JMS connector’s configuration.

  3. Refer to the table below to learn more about the setting the value of the maxDelivery attributes.

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 value 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 in the flow 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.

STUDIO Visual Editor

  1. In the Global Elements tab, create a Rollack Exception Strategy.

  2. Refer to step 2 Configuring a Rollback Exception Strategy to configure your global rollback exception strategy.

  3. 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.

    global_rollback_ES

  4. Follow steps 3 - 5 Configuring a Rollback Exception Strategy to build your global rollback exception strategy flow and redelivery exhausted flow.

XML Editor or Standalone

  1. Above all the flows in your application, create a rollback-exception-strategy element.

  2. To this global rollback-exception-strategy element, add the attributes according to step 2 Configuring a Rollback Exception Strategy.

  3. Follow steps 3 - 5 Configuring a Rollback Exception Strategy to build your global rollback exception strategy flow and redelivery exhausted 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.

STUDIO Visual Editor

  1. From the Error Handling palette group, drag and drop the Reference Exception Strategy icon into the footer bar of a flow.

    reference_ES

  2. Double-click to open the Reference Exception Strategy Pattern Properties panel.

    global_reference

  3. Use the drop-down to select your Global Exception Strategy.

  4. Click OK to save your changes.

    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 (plus) button next to the Global Exception Strategy drop-down and follow the steps above to create a global choice exception strategy.

XML Editor or Standalone

  1. In your flow, below all the message processors, add a reference-exception-strategy element. Refer to code below.

  2. Configure attributes of the exception strategy according to the table below.

    Attribute Req’d Value

    ref

    x

    The name of the global exception strategy to which your flow should refer to handle exceptions.

    doc:name

    x

    A unique name for the rollback exception strategy in your application.
    Not required in Standalone.

    		 
    <exception-strategy ref="Global_Rollback_Exception_Strategy" doc:name="Reference Exception Strategy"/>
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.

See Also