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

  5. Choice Exception Strategy

Choice Exception Strategy

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

You can define a choice exception strategy to customize the way Mule handles a message with an error based on the message’s content at the moment it throws an exception. A choice exception strategy catches all exceptions thrown within its parent flow, examines message contents and exception type, then routes messages to the appropriate exception strategy for processing.

Usually, you define more than one exception strategy within a choice exception strategy. Each exception strategy – either catch or rollback – uses a Mule expression to advise the choice exception strategy which type of messages it accepts and processes.

Here’s how it works: when the choice exception strategy catches an exception, it evaluates the type of exception and the message contents at the time the error occurred. Then it checks the expression attribute of each of its exception strategies one by one, serially, to see which one of them should handle the error. It then routes the message to the first exception strategy that evaluates to true (has an expression that matches the expression of the message). If none of its exception strategies can handle the error, the choice exception strategy routes the message to Mule’s default exception strategy.

  • You can put any number of catch or rollback exception strategies into a choice exception strategy.

  • You cannot put a choice exception strategy inside another choice exception strategy.

  • You can use any Mule expression evaluator as the expression attribute of an exception strategy. Consider using an exception-type expression evaluator, such as org.mule.example.ValidationException, when you need to route messages based on the type of exception they throw.

When to Use

Use a choice exception strategy to enable Mule to make decisions about how to handle each error that occurs in a flow.

For example, in a flow that processes orders, you can use a choice exception strategy to apply the following error handling rules:

  • Messages that throw an AlreadyProcessedException should be discarded.

  • Messages that throw a ValidationException should be sent to an invalid order queue.

  • All other messages which throw exceptions should be rolled back to retry processing.

A choice exception strategy can evaluate the exception type of each message that throws an exception in this flow and route them to one of three exception strategies:

  • A catch exception strategy to process and discard all AlreadyProcessedExceptions.

  • A second catch exception strategy to process all ValidationExceptions and send them to an invalid.orders queue.

  • A rollback exception strategy to roll back the order transaction in order to retry processing in the parent flow.

The following are useful expressions that check for specific exceptions:

  • Instance of: Checks that the exception is an instance of ExceptionType.
    Syntax: #[exception.causedBy(ExceptionType)]
    Example: #[exception.causedBy(java.lang.IllegalArgumentException)]

  • Exact Match: Checks that the exception exactly matches the ExceptionType.
    Syntax: #[exception.causedExactlyBy(ExceptionType)]
    Example: #[exception.causedExactlyBy(java.net.SocketTimeoutException)]

  • Regular Expression Match: Checks that the exception type matches a particular regular expression (Regex) String. Syntax: #[exception.causeMatches(String)]
    Example: #[exception.causeMatches('*BusinessException')]

Configuring a Choice Exception Strategy

Studio Visual Editor

  1. Search for "choice" and drag and drop the choice exception strategy icon into the footer bar of a flow.

    choice+1

  2. Click the title bar of the exception strategy to open its Properties Editor, then enter a name for your choice exception strategy in the Display Name field.

  3. Search for "rollback" and drag and drop one or more catch or rollback exception strategy icons into the choice exception strategy box.

    Keep in mind that the choice exception strategy checks the expression attribute of each of its exception strategies one by one, serially, to see which one should handle the error; it then routes the message to the first exception strategy that evaluates to true. Therefore, organize your exception strategies keeping in mind that the top-most evaluates first, then the one below it, and so on. You cannot rearrange the exception strategies once they have been placed inside the choice exception strategy. You can always resort to the XML view of your project to rearrange their order if necessary.
    choice+2

  4. Follow the instructions to define and configure each catch exception strategy and rollback exception strategy. Be sure to enter a Mule expression in the Execute When field or the XML when parameter of each catch or rollback (respectively) exception strategy that you put into the choice exception strategy. The contents of Execute When or when determine what kind of errors the exception strategy accepts and processes.

    You can leave the Execute When field blank in the last exception strategy configured inside your choice exception strategy. An exception strategy with a blank Execute When field accepts and processes any and all kinds of exceptions that messages throw in the parent flow.

  5. Search for and drag processors from the palette into each catch exception strategy and rollback exception strategy box to build flows to process messages with errors. Each catch and rollback exception strategy can contain any number of message processors.

    choice+3

XML Editor or Standalone

  1. In your flow, below all the message processors, add a choice-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.

    		 
    <choice-exception-strategy doc:name="Choice Exception Strategy"/>

  3. As child elements, add one or more catch or rollback exception strategy icons to your choice exception strategy.

    Keep in mind that the choice exception strategy checks the expression attribute of each of its exception strategies one by one, serially, to see which one of them should handle the error; it then routes the message to the first exception strategy that evaluates to true. Therefore, organize your exception strategies keeping in mind that the top-most evaluates first, then the one below it, and so on. 
    <flow name="Sample_Flow">
...
<choice-exception-strategy doc:name="Choice Exception Strategy">
    <catch-exception-strategy doc:name="Catch Exception Strategy"/>
    <rollback-exception-strategy doc:name="Rollback Exception Strategy"/>
</choice-exception-strategy>
</flow>

  4. Follow the instructions to define and configure each catch exception strategy and rollback exception strategy. Be sure to define a Mule expression as the value of the when attribute of each catch or rollback (respectively) exception strategy that you have put into the choice exception strategy. The value of the when attributes determine what kind of errors the exception strategy accepts and processes.

    You can leave the value of the when attribute empty in the last exception strategy configured inside your choice exception strategy. An exception strategy with an empty when attribute accepts and processes any and all kinds of exceptions that messages throw in the parent flow.

  5. Add message processors as child elements in each catch exception strategy and rollback exception strategy to build exception strategy flows to process messages with errors. Each catch and rollback exception strategy can contain any number of message processors.

    <flow name="Sample_Flow">
...
    <choice-exception-strategy doc:name="Choice Exception Strategy">
        <catch-exception-strategy doc:name="Catch Exception Strategy" when="#[exception.causedBy(org.mule.api.routing.filter.FilterUnacceptedException)]">
            <set-variable variableName="errorStatusCode" value="404" doc:name="Set status code"/>
            <set-variable variableName="errorReasonPhrase" value="Not Found" doc:name="Set reason phrase"/>
        </catch-exception-strategy>
        <rollback-exception-strategy doc:name="Rollback Exception Strategy">
            <logger level="INFO" doc:name="Logger" message="Unknown error"/>
        </rollback-exception-strategy>
    </choice-exception-strategy>
</flow>

Creating a Global Choice Exception Strategy

Visual Studio Editor

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

  1. Click File > New > Mule Configuration File. You can use this configuration file to store the processors to share with all the flows in your project. This file appears in your Studio project under src/main/app. For this example, you can name it global.xml. The configuration file has the same elements the same as a Mule project so you can search for and drag processors into the configuration file.

  2. Click Message Flow and copy the processors you want in the configuration file. The catch exception strategy should be in the configuration file.

    choice+4

  3. Follow Configuring a Choice Exception Strategy to configure exception strategies within your choice exception strategy, then define the flows to handle errors when they occur.

XML Editor or Standalone

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

  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.

  3. Follow Configuring a Choice Exception Strategy to configure exception strategies within your choice exception strategy, then define the flows to handle errors when they occur.

Applying a Global Choice Exception Strategy to a Flow

Studio Visual Editor

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

  1. Search for "reference" and drag and drop the Reference Exception Strategy icon into the footer bar of a flow.

    reference+1

  2. Open the Reference Exception Strategy’s Properties Editor.

    choice+setup+choice

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

  4. Save your project.

XML Editor or Standalone

  1. In your flow, below all the message processors, add a reference-exception-strategy element. Refer to the 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_Choice_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