The broker provides basic error handling for all your message flows. If basic processing is not sufficient, and you want to take specific action in response to certain error conditions and situations, you can enhance your message flows to provide your own error handling.
For example, you might design a message flow that expects certain errors that you want to process in a particular way, or a flow that updates a database and must roll back those updates if other processing does not complete successfully.
The options that you can use to do this are quite complex in some cases. The options that are provided for MQInput and TimeoutNotification nodes are extensive because these nodes deal with persistent messages and transactions. The MQInput node is also affected by configuration options for WebSphere® MQ.
Because you can decide to handle different errors in different ways, there are no fixed procedures to describe. This section provides information about the principles of error handling, and the options that are available, and you must decide what combination of choices that you need in each situation based on the details that are provided in this section.
You can choose one or more of these options in your message flows:
- Connect the Failure terminal of any node to a sequence of nodes that processes the node's internal exception (the fail flow).
- Connect the Catch terminal of the input node or a TryCatch node to a sequence of nodes that processes exceptions that are generated beyond it (the catch flow).
- Insert one or more TryCatch nodes at specific points in the message flow to catch and process exceptions that are generated by the flow connected to the Try terminal.
- Include a Throw node, or code an ESQL THROW statement, to generate an exception.
- Connect the Catch terminal of the AggregateReply node to process aggregation exceptions if you are using aggregation.
- Ensure that all of the messages received by an MQInput node are processed within a transaction, or are not processed within a transaction.
- Ensure that all of the messages received by an MQInput node are persistent, or are not persistent.
If you include user-defined nodes in your message flow, you must see the information provided with the node to understand how you might handle errors with these nodes. The descriptions in this section cover only the built-in nodes.
When you design your error handling approach, consider the following factors:
- Most of the built-in nodes have Failure terminals. The exceptions are the AggregateControl, AggregateRequest, Input, Label, Output, Passthrough, Publication, Real-timeInput, Real-timeOptimizedFlow, Throw, Trace, and TryCatch nodes.
When an exception is detected within a node, the message and the exception information are propagated to the node's Failure terminal. If the node does not have a Failure terminal, or it is not connected, the broker throws an exception and returns control to the closest previous node that can process it. This might be a TryCatch node, an AggregateReply node, or the input node.
If an MQInput node detects an internal error, its behavior is slightly different; if the Failure terminal is not connected, it attempts to put the message to the input queue's backout requeue queue, or (if that is not defined) to the dead letter queue of the broker's queue manager.
For more information, see Handling MQInput errors.
- A small number of built-in nodes have Catch terminals. These are the AggregateReply, HTTPInput, MQInput, SCADAInput, JMSInput, JMSOutput, TimeoutNotification, and TryCatch nodes.
A message is propagated to a Catch terminal only if it has first been propagated beyond the node (for example, to the nodes connected to the Out terminal).
- When a message is propagated to the Failure or Catch terminal, the node creates and populates a new ExceptionList with an exception that represents the error that has occurred. The ExceptionList is propagated as part of the message tree.
- The MQInput and TimeoutNotification nodes have additional processing for transactional messages (other input nodes do not handle transactional messages).
For more information, see Handling MQInput errors and Handling TimeoutNotification errors.
- If you include a Trace node that specifies $Root or $Body, the complete message is parsed. This might generate parser errors that are not otherwise detected.
The general principles of error handling are:
- If you connect the Catch terminal of the input node, you are indicating that the flow handles all of the exceptions that are generated anywhere in the out flow. The broker performs no rollback and takes no action unless there is an exception on the catch flow. If you want any rollback action after an exception has been raised and caught, you must provide this in the catch flow.
- If you do not connect the Catch terminal of the MQInput or the HTTPInput node, you can connect the Failure terminal and provide a fail flow to handle exceptions generated by the node. The fail flow is started immediately when an exception occurs in the node.
The fail flow is also started if an exception is generated beyond the MQInput node (in either out or catch flows), the message is transactional, and the reinstatement of the message on the input queue causes the backout count to reach the backout threshold.
The HTTPInput and SCADAInput nodes do not propagate the message to the Failure terminal if an exception is generated beyond the node and you have not connected the Catch terminal.
- If a node propagates a message to a catch flow, and another exception occurs that returns control to the same node again, the node handles the message as though the Catch terminal is not connected.
- If you do not connect either the Failure or Catch terminals of the input node, the broker provides default processing (which varies with the type of input node).
- If you need a more comprehensive error and recovery approach, include one or more TryCatch nodes to provide more localized areas of error handling.
- If you have a common procedure for handling particular errors, you might find it appropriate to create a subflow that includes the sequence of nodes required. Include this subflow wherever you need that action to be taken.
For more information, see Connecting failure terminals, Managing errors in the input node, and Catching exceptions in a TryCatch node.
If your message flows include database updates, the way in which you configure the nodes that interact with those databases can also affect the way that errors are handled:
- You can specify whether updates are committed or rolled back. You can set the node property Transaction to specify whether database updates are committed or rolled back with the message flow (option Automatic), or are committed or rolled back when the node itself terminates (option Commit). You must ensure that the combination of these property settings and the message flow error processing give the correct result.
- You can specify how database errors are handled. You can set the properties Treat warnings as errors and Throw exception on database error to change the default behavior of database error handling.
For more information about coordinated database updates, see Configuring globally coordinated message flows.
Message flows for aggregation involve additional considerations that are not discussed in this topic. For information about message flows for aggregation, see Handling exceptions in aggregation flows.
The following sample demonstrates how to use an error handling routine to trap information about errors and to store that information in a database. The error handling routine is a subflow that you can add, unchanged, to any message flow. The sample also demonstrates how to configure message flows to control transactionality; in particular, the use of globally coordinated transactions to ensure overall data integrity.
You can view samples only when you use the information
center that is integrated with the Message Brokers Toolkit.