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 refer to 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 the following:
- 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 the following topics:
- 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 the following topics:
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 the following topic:
Message flows for aggregation involve additional
considerations that are not discussed in this section; these are described
in the following topic:
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.