You can define a catch exception strategy to customize the way Mule handles messages with errors. A catch exception strategy catches all exceptions thrown within its parent flow and processes them, thereby overriding Mule’s implicit default exception strategy.
Mule’s catch exception strategy behavior is similar to a Java catch block, except that you cannot throw a new exception or catch another exception within a catch exception strategy.
Use a catch exception strategy to design a unique strategy for handling a message that contains an error. Further, you can use a catch exception strategy to:
-
avoid propagating exceptions to inbound connectors
-
avoid propagating exceptions to parent flows via Flow Reference Components
-
ensure that a transaction processed by the flow will not be rolled back when an error occurs (i.e. The transaction is never “rolled back” to reattempt processing; Mule commits the transaction.)
For example, suppose you have a flow that processes messages from a JMS queue (a reservation for a flight), enriches them by adding a property acquired from an external resource (seat assignment), and then sends them to another queue. You configure a catch exception strategy to handle errors that occur in this flow; when an error occurs during processing — say the seat information is not available from the external resource — the message throws an exception. The catch exception strategy catches the exception, applies a header to it to advise that “no seats are available,” and pushes the message out of the flow to its next designated queue.
[tab,title="Studio Visual Editor"] .... image:catch+1.png[catch+1] .... [tab,title="Studio XML Editor or Standalone"] .... [source, xml, linenums] ---- <?xml version="1.0" encoding="UTF-8"?> <mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:jms="http://www.mulesoft.org/schema/mule/jms" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:vm="http://www.mulesoft.org/schema/mule/vm" xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd"> <jms:activemq-connector name="Active_MQ" brokerURL="tcp://localhost:61616" validateConnections="true" doc:name="Active MQ"/> <http:request-config name="HTTP_request_Configuration" host="localhost" port="8081" doc:name="HTTP Request Configuration"/> <flow name="makeReservation" > <jms:inbound-endpoint queue="seatAssigment" connector-ref="Active_MQ" doc:name="Seat assigment queue"/> <enricher target="#[flowVars['seatInfo']]" doc:name="Create seatInfo variable with seat assigment"> <http:request config-ref="HTTP_request_Configuration" path="seatService" method="GET" doc:name="Seat assigment web service"/> </enricher> <set-property propertyName="seatInfo" value="#[flowVars['seatInfo'].getSeatNumber()]" doc:name="Set seatInfo jms property"/> <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/> <catch-exception-strategy doc:name="Catch Exception Strategy"> <set-property propertyName="seatInfo" value="No seat info available" doc:name="Set seatInfo jms property"/> <jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/> </catch-exception-strategy> </flow> </mule> ---- ....
[tab,title="Studio Visaul Editor"]
....
. From the *Error Handling* palette group, drag and drop the *Catch Exception Strategy* icon into the footer bar of a flow.
+
image:catch+2.png[catch+2]
. Open the Catch Exception Strategy's *Properties Editor*, then configure according to the table below.
+
image:catch+3.png[catch+3]
+
[%header%autowidth.spread]
|===
|Field |Value
|*Display Name* |Unique name for the exception strategy, if you wish.
|*Execute When* a|A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a link:/mule-user-guide/v/3.8/choice-exception-strategy[Choice Exception Strategy]
• *no expression defined*: All messages in this flow that throw exceptions will be handled by this catch exception strategy. +
• *expression defined*: When a choice exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy. +
For example, if you enter the following expression, the exception strategy handles only those messages which throw an org.mule.example.AlreadyProcessedException.
[source, code, linenums]
----
#[exception.causedBy(org.mule.example.AlreadyProcessedException)]
----
|*Enable Notifications* |true (_default_) +
false +
When set to true, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.
|===
+
[TIP]
====
What follows are some examples of expressions that you can enter in the *Execute 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)`
====
. Click anywhere on the canvas to save your configurations.
. Drag building blocks from the palette into the *Catch Exception Strategy* box to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors.
+
image:catch+4.png[catch+4]
+
[NOTE]
====
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 link:/mule-user-guide/v/3.8/choice-exception-strategy[Choice Exception Strategy].
====
....
[tab,title="Studio XML Editor or Standalone"]
....
. To your flow, below all the message processors, add a *`catch-exception-strategy`* element. Refer to code below.
. Configure attributes of the exception strategy according to the table below.
+
[%header%autowidth.spread]
|===
|Attribute |Value
|*doc:name* |Unique name for the exception strategy, if you wish. (Not required in Standalone.)
|*when* |A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a link:/mule-user-guide/v/3.8/choice-exception-strategy[*Choice Exception Strategy*]. +
• *no expression defined*: All messages in this flow that throw exceptions will be handled by this catch exception strategy. +
• *expression defined*: When a choice exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy. +
For example, if you enter the following expression, the exception strategy handles only those messages which throw an org.mule.example.AlreadyProcessedException.
|*enableNotifications* |true or false +
When set to true, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception.
|===
+
[TIP]
====
What follows are some examples of expressions that you can use as values of the `when` attribute:
* `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)`
====
+
[source, xml, linenums]
----
<jms:activemq-connector name="Active_MQ" brokerURL="tcp://localhost:61616" validateConnections="true" doc:name="Active MQ"/>
<http:request-config name="HTTP_request_Configuration" host="localhost"
port="8081" doc:name="HTTP Request Configuration"/>
<flow name="makeReservation" doc:name="makeReservation">
<jms:inbound-endpoint queue="seatAssigment" connector-ref="Active_MQ" doc:name="Seat assigment queue"/>
<enricher target="#[flowVars['seatInfo']]" doc:name="Create seatInfo variable with seat assigment">
<http:request config-ref="HTTP_request_Configuration" path="seatService" method="GET" doc:name="Seat assigment web service"/>
</enricher>
<set-property propertyName="seatInfo" value="#[flowVars['seatInfo'].getSeatNumber()]" doc:name="Set seatInfo jms property"/>
<jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>
<catch-exception-strategy doc:name="Catch Exception Strategy" enableNotifications="true" />
</flow>
----
*_View the Namespace_*
[source, xml, linenums]
----
<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:jms="http://www.mulesoft.org/schema/mule/jms" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:core="http://www.mulesoft.org/schema/mule/core" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:vm="http://www.mulesoft.org/schema/mule/vm" xmlns:scripting="http://www.mulesoft.org/schema/mule/scripting" xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/current/mule-jms.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd
http://www.mulesoft.org/schema/mule/scripting http://www.mulesoft.org/schema/mule/scripting/current/mule-scripting.xsd
http://www.mulesoft.org/schema/mule/ee/core http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd">
----
[start=3]
. Add message processors as child elements of the `catch-exception-strategy` to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors. Refer to sample code below in which a `set-property` and `jms:outbound-endbpoint` process exceptions.
+
[source, xml, linenums]
----
<flow name="makeReservation" doc:name="makeReservation">
...
<catch-exception-strategy doc:name="Catch Exception Strategy">
<set-property propertyName="seatInfo" value="No seat info available" doc:name="Set seatInfo jms property"/>
<jms:outbound-endpoint queue="checkin" connector-ref="Active_MQ" doc:name="Check-In queue"/>
</catch-exception-strategy>
</flow>
----
+
[NOTE]
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 link:/mule-user-guide/v/3.8/choice-exception-strategy[Choice Exception Strategy].
....
You can create one or more global exception strategies to reuse in flows throughout your entire Mule application. First, create a global catch exception strategy, then add a Reference Exception Strategy to a flow to apply the error handling behavior of your new global catch exception strategy.
[tab,title="Studio Visual Editor"] .... . In the Global Elements tab in Studio, create a *Global Catch Exception Strategy* (below, left), configure it according to the table below (refer to image below, right), then click *OK* to save. + + image:catch_global_both.png[catch_global_both] + [%header,cols="2*"] |=== |Field |Value |*Display Name* |Unique name for the exception strategy, if you wish. |*Execute When* a|A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a link:/mule-user-guide/v/3.8/choice-exception-strategy[*Choice Exception Strategy*]. + • *no expression defined*: All messages in this flow that throw exceptions will be handled by this catch exception strategy. + • *expression defined*: When a choice exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy. + For example, if you enter the following expression, the exception strategy handles only those messages which throw an org.mule.example.AlreadyProcessedException. [source, code, linenums] ---- #[exception.causedBy(org.mule.example.AlreadyProcessedException)] ---- |*Enable Notifications* |true (_default_) + false + When set to true, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception. |=== . Click on the *Message Flow* tab below the canvas. On the Message Flow canvas, note that your newly created global catch exception strategy box appears _outside_ all other flows in the application. Because it is global, your new catch exception strategy exists independently of any Mule flow. + image:catch+global.png[catch+global] . Drag building blocks from the palette into the global catch exception strategy box to build a flow that processes messages that throw exceptions. A global catch exception strategy can contain any number of message processors. .... [tab,title="Studio XML Editor or Standalone"] .... . Above all the flows in your application, create a *`c`***`atch-exception-strategy`** element. . To this global `catch-exception-strategy` element, add the attributes according to the table below. Refer to code sample below. + [%header%autowidth.spread] |=== |Attribute |Value |*name* |Unique name for the exception strategy, if you wish. |*when* |A MEL expression to indicate the kind of exception the catch exception strategy handles when it is embedded within a link:/mule-user-guide/v/3.8/choice-exception-strategy[*Choice Exception Strategy*]. + • *no expression defined*: All messages in this flow that throw exceptions will be handled by this catch exception strategy. + • *expression defined*: When a choice exception strategy evaluates the defined expression against the message being processed and returns true, Mule executes the exception strategy. + For example, if you enter the following expression, the exception strategy handles only those messages which throw an org.mule.example.AlreadyProcessedException. |*enableNotifications* |true or false + When set to true, Mule sends an exception notification to a registered listener — say, the Mule Management Console — whenever the catch exception strategy accepts handles an exception. |=== + [source, xml, linenums] ---- <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081"/> <catch-exception-strategy name="Catch_Exception_Strategy"/> <flow name="Creation1Flow1" doc:name="Creation1Flow1"> <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP Connector"/> <cxf:jaxws-service doc:name="SOAP"/> ... </flow> ---- *_View the Namespace_* [source, xml, linenums] ---- <mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd"> ---- [start=3] . Add message processors as child elements of the `catch-exception-strategy` to build a flow that processes messages that throw exceptions in the parent flow. A catch exception strategy can contain any number of message processors. Refer to sample code below in which a simple `logger` processes exceptions. + [source, xml, linenums] ---- <catch-exception-strategy name="Catch_Exception_Strategy"> <logger message="#[payload]" level="INFO" doc:name="Logger"/> </catch-exception-strategy> <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081"/> <catch-exception-strategy name="Catch_Exception_Strategy"/> <flow name="Creation1Flow1" doc:name="Creation1Flow1"> <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP Connector"/> <cxf:jaxws-service doc:name="SOAP"/> ... </flow> ---- ....
Use a reference exception strategy to instruct a flow to employ the error handling behavior defined by your global catch 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.
[tab,title="Studio Visual Editor"] .... . From the *Error Handling* palette group, drag and drop the *Reference Exception Strategy* icon into the footer bar of a flow. + image:reference+exception+1.png[reference+exception+1] . Open the Reference Exception Strategy's Properties Editor, use the drop-down to reference the global catch exception strategy (below); click anywhere on the canvas to save. + image:reference+exception+2.png[reference+exception+2] + [TIP] ==== 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. ==== .... [tab,title="Studio XML Editor or Standalone"] .... . To your flow, below all the message processors, add an **`exception-strategy`** element. . To the `exception-strategy` element, add attributes according to the table below. Refer to code below. + [source, xml, linenums] ---- <catch-exception-strategy name="Catch_Exception_Strategy"> <logger message="#[payload]" level="INFO" doc:name="Logger"/> </catch-exception-strategy> <http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081"/> <flow name="Creation1Flow1" doc:name="Creation1Flow1"> <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP Connector"/> <cxf:jaxws-service doc:name="SOAP"/> ... <exception-strategy ref="Catch_Exception_Strategy" doc:name="Reference Exception Strategy"/> </flow> ---- + [%header%autowidth.spread] |=== |Attribute |Value |*ref* |Name of the global `catch-exception-strategy` in your project. |*doc:name* |Unique name for the exception strategy, if you wish. (Not required in Standalone.) |=== + [TIP] 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. ....
-
Learn how to configure rollback exception strategies.
-
Learn how to configure choice exception strategies.