About the Error Handler sample

The Error Handler sample is based on a scenario where a business involved in processing transactions wants to develop a routine for handling errors. The sample demonstrates how to use some of the features provided in WebSphere Message Broker.

Businesses such as banks want to make sure that transactions are processed once and only once, and that there is a record of any errors. In the Error Handler sample, you put messages about staff numbers through a message flow that updates a database with this information. By putting in a message with an invalid staff number, you can observe how the error handling routine works.

The Error Handler sample demonstrates the following tasks:

The messages

Two input messages are supplied for running the Error Handler sample: a message that contains a valid staff serial number, and a message that contains an invalid staff serial number.

The valid staff message is rendered in XML as follows:

<Staff>
   <StaffNumber>1</StaffNumber>
   <NameInfo>
      <LastName>Smith</LastName>
      <FirstName>Jack</FirstName>
   </NameInfo>
</Staff>

 

The invalid staff message is rendered in XML as follows:

<Staff>
   <StaffNumber>99</StaffNumber>
   <NameInfo>
      <LastName>Doe</LastName>
      <FirstName>Jane</FirstName>
   </NameInfo>
</Staff>

 

The message flows

The following figure shows the main message flow.

A screen capture of the main message flow.

The following figure shows the error handling subflow.

A screen capture of the error handling subflow.

The following table lists the types of nodes that are used in the Error Handler sample. The Subflow node is not technically a node and it is not available in the Node Palette; the Subflow node just represents where the subflow, Error_Handler.msgflow, is called within the main message flow.

Node type Node name
MQInput STAFF_IN
MQOutput STAFF_FAIL; STAFF_OUT
Database Update Staff Database; Update Error Database
Filter Check Valid Staff Number; Check Backout Count
Throw Throw; Throw to Complete Rollback
TryCatch TryCatch
Subflow Error_Handler

For more information, read about the nodes in the Error Handler sample's message flows in the WebSphere Message Broker documentation.

The route taken by the valid staff message

When you put the valid staff message on the input queue, the message travels through the nodes as described below. If any of the queues have been disabled, the message will not be able to follow this path.

In the main message flow:

  1. STAFF_IN. The node gets the input message from the input queue.
  2. Error_Handler. This node represents the error handling subflow. The message now leaves the main message flow, and enters the subflow.

In the subflow:

  1. Start Subflow. The message is passed to the next node in the flow.
  2. Check Backout count. The node checks whether the backout count is zero. As this is the first time the input message is passing through this node, the count is currently zero, and the message is passed to the next node. If the count is more than zero, the message is discarded.
  3. TryCatch. Because the staff number is valid, the message is passed to the Back To Main Flow node. If the staff number in the message is invalid, and the processing of the message has proceeded to a stage where this had been discovered, the message is passed to the Update Error Database node instead.
  4. Back To Main Flow. At this point, the message leaves the subflow, and returns to the main message flow.

In the main message flow:

  1. Check Valid Staff Number. Because the staff number is valid, the message is passed to the Update Staff Database node.
  2. Update Staff Database. The STAFFDB database is updated with the staff details in the message.
  3. STAFF_OUT. The node puts the message on the STAFF_OUT queue.

The route taken by the invalid staff message

When you put the invalid staff message on the input queue, the message travels through the nodes as described below. If any of the queues have been disabled, the message will not be able to follow this path. For more information about what each node does, click the nodes in the figures in the main topic.

In the main message flow:

  1. STAFF_IN. The node gets the input message from the input queue.
  2. Error_Handler. This node represents the error handling subflow. The message now leaves the main message flow, and enters the subflow.

In the subflow:

  1. Start Subflow. The message is passed to the next node in the flow.
  2. Check Backout Count. The node checks whether the backout count is zero. As this is the first time the input message is passing through this node, the count is currently zero, and the message is passed to the next node. Compare to step 13, below.
  3. TryCatch. The staff number in the message is invalid, but this has not been discovered yet. As a result, the input message is passed to the Back To Main Flow node, rather than to the Update Error Database node.
  4. Back To Main Flow. At this point, the message leaves the subflow, and returns to the main message flow.

In the main message flow:

  1. Check Valid Staff Number. Because the staff number is invalid, the message is passed to the Throw Exception node, rather than to the Update Staff Database node.
  2. Throw Exception. The node stops the processing of the message, and records the error number "3001", and the text "Invalid staff number" to the message content. The message is now 'rolled back'. That is, the message is propagated back to the point of control, which in this case is the TryCatch node in the subflow.

In the subflow:

  1. TryCatch. The node recognises that there has been an exception in the processing of the message, and passes the message to the Update Error Database node.
  2. Update Error Database. The ERRORDB database is updated with the details of the error, as set in the Throw exception node (step 8).
  3. Throw To Complete Rollback. The node stops the processing of the message, and records the number "3002", and the text "From Error_Handler message flow. See ERRORDB for details" to the message content. The message is now propagated back to the point of control, which is the STAFF_IN node in the main message flow.
    This is the final stage of the catch processing. It has the effect of rolling back the entire transaction, including the database updates under transactional control (that is, the STAFFDB update in the main flow) on the original try path. However, the ERRORDB update, which is outside transactional control, is still committed.

In the main message flow:

  1. STAFF_IN. As there has been an exception in the processing of the message, the message is passed to the STAFF_FAIL node, rather than passed through the message flow again.
  2. STAFF_FAIL. The node puts the message on the STAFF_FAIL queue. Alternatively, if the STAFF_FAIL queue is disabled, the message does not stop here. It is passed back to the STAFF_IN node, and then to the subflow. The message then reaches the Check Backout Count node. The node checks whether the backout count is zero. As the message has passed through this node previously, the backout count is no longer zero, and the message is discarded. Discarding the message prevents a situation where, if the STAFF_FAIL queue is disabled, the message keeps travelling through the flow over and over again. Compare to step 4, above.

When you use a TryCatch node, or when you attach nodes to the Catch terminal of an MQInput node, you might assume that any processing that has occurred on the try path will not, if the nodes are correctly configured, be committed if the catch path is invoked. This, however, is not the case. For example, if a database is updated on the try path under transactional control, and the catch path is invoked and completes normally, the database update will still be committed.

The requirement in this sample is to read a message, update a database, and write the message on another queue. If an error occurs, the database update is rolled back. Catch processing updates the error database with the details of the error, and writes the original message to the failure queue. In programming terms, this is what happens:

BEGIN (Start 'outer' unit-of-work.)
MQGET (Get message from the input queue.)
TRY
   BEGIN (Start 'inner' unit-of-work.)
   Update database
   MQPUT (Put message onto the output queue.)
   IF ERROR
      ROLLBACK inner unit-of-work GO TO CATCH
   ELSE
      COMMIT inner and outer unit-of-work as one unit-of-work
   END IF
CATCH
   Update error database
   MQPUT (Put message onto the failure queue.)
   COMMIT outer unit-of-work

However, XA Transaction Manager and WebSphere MQ do not support two levels of unit-of-work in the same application. As a result, Error Handler sample uses the following structures:

There are two databases in this sample, rather than just one, because in WebSphere MQ the same database connection cannot be used for both coordinated and uncoordinated transactions in the same message flow. In the Error Handler sample, the database update in the main message flow is under transactional control so that if an error occurs, the update rolls back and is not committed. The database update in the subflow is not under transactional control so that the update is always committed. As a result, the Error Handler sample requires two separate databases.

For more information, read about coordinating transactions in message flows in the WebSphere Message Broker documentation.

Back to sample home