Integrating applications using WebSphere Message Broker: Part 6 -- Debugging message flows using Websphere Message Broker

This article series provides the information you need to build, deploy, debug, and run a Web Order Processing Application sample using the tooling features of WebSphere® Message Broker. This article, Part 6 of a six-part series, shows you how to use WebSphere Message Broker flow debugger and source debuggers to debug basic to complex applications. WebSphere Message Broker debugging capabilities make it easy for you to track both the control and data flow of your applications. The information in this article applies to WebSphere Message Broker Version 5.0.2 and above. You can begin with Part 1 of this series, Integration scenario for creating a Web order processing application, to get the background you need for this article.

Shu Tan (shutan@ca.ibm.com), Staff Software Developer, IBM

Shu Tan is a staff software developer at IBM Toronto Laboratory in the Toronto, Ontario. She works on the debugger for Websphere Message Broker.



Vivian Mak (vivmak@ca.ibm.com), Staff Software Developer, IBM

Vivian Mak is a staff software developer at IBM Toronto Laboratory in the Toronto, Ontario. She works on the debugger for Websphere Message Broker.



Evan Mamas (cserna@us.ibm.com), Staff Software Developer, IBM

Evan Mamas was a Staff Software Developer at IBM Toronto Laboratory in the Toronto, Ontario. He is now a graduate student at MIT.



04 October 2005

Introduction

You can use the flow debugger in WebSphere Message Broker to debug flows in a WebOrder sample that consists of a variety of nodes such as ESQL nodes, mapping nodes, as well as user-defined Java™ plug-in nodes. This article highlights the debugging capabilities in WebSphere Message Broker and demonstrates how the flow debugger seamlessly integrates flow debugging, ESQL source debugging, and Java source code debugging, thus maximizing your productivity.


Getting started

To use all the debugging functionality described in this article, you need:

  • WebSphere Message Broker 5.0.2 and above.
  • IBM Agent Controller installed on the system that hosts the Broker (Version 5.0.2).
  • A basic understanding of the following concepts:
    • Java and J2EE technology
    • XML
    • Flow Editor
    • ESQL
    • Mapping Nodes
    • Java Plug-in nodes
    • The overall scenario that begins with the article, Integrating applications using Websphere Business Integration Message Broker V5 – Part 1: Integration scenario for creating a Web order processing application.
  • Follow the workspace setup instructions in Part 1 to import projects and create a broker, configuration manager, database tables, and queues.

Debugging basics

You can follow some basic steps (see below) to use the flow debugger in WebSphere Message Broker. You can use these steps for every flow debugging activity.

  1. Attach the debugger to the flow run time.

    Once the flow has been deployed, you will have to attach the Flow Debugger to the execution group that is running the flow.
    1. Open the Flow Debug Perspective and click on the Attach To Flow Engine toolbar button Attach To Flow Engine.
    2. When prompted by the wizard, specify the host where the broker is running and select the name of the execution group to which you wish to attach the debugger. Once the debugger is attached, the Flow Debug View will be updated to list the flows that are currently deployed in the attached execution group. You can use the debugger to attach to multiple execution groups at the same time.

      Important: Make sure that the debugger is not attached when you perform a deploy operation.
  2. Invoke the flow.
    1. Select File => New => Message Enqueue File to create an enqueue file.
    2. Give a name to enqueue. This article uses the name: SampleTestMessage.enqueue.
    3. In the editor, specify the Queue Manager name: WEBOQMGR and the Input Queue Name: ORDER.REQUEST.Q00
    4. Load the file that contains the actual message to be deployed in the queue. You can use any xml file located in the sourceMessages\purchaseOrders folder of WebOrderPurchaseOrder project.
    5. Click the Write to Queue button to submit the message to the flow.

Flow debugging

You can use this section to debug your message flows.

Flow breakpoints

Breakpoints are always associated with connections. To add or remove a breakpoint, you can right-click on a connection and select the corresponding action. Another convenient way to add breakpoints is by adding them before or after a given node. The Flow Breakpoints View provides a list of all the flow breakpoints in the workbench. You can selectively enable, disable, change properties, and remove any flow breakpoint from this view. For our debug scenario, you will need to add three breakpoints as illustrated below. Once you add the breakpoints, you can also observe how the contents of the Flow Breakpoints View are updated.

Figure 1. Flow Debugger Perspective
Flow Debugger Perspective
Figure 2. Flow breakpoint
Flow breakpoint

Flow instances

Now that you have set the flow breakpoints, you can invoke the flow by using the SampleTestMessage.enqueue file. As soon as the message is submitted, the workbench will switch to the Perspective and the first breakpoint is highlighted. In the Flow Debug View, a list of all the flows that are deployed in the execution group are shown. Under the processPurchaseOrderFlow, there are two more levels of detail:

  1. The Thread ID, 2668 in this case, represents the thread that processes the input message through the flow.
  2. The Flow Stack represents the nesting of flows at this execution point in the flow.

It is worth mentioning that users are able to debug multiple flow threads (that is, multiple messages) at the same time. The allowMultipleInstances setting can be adjusted (through the deploy parameters) to determine how many messages can be processed by a given flow simultaneously.

Flow debug controls

To resume the flow execution, click the Resume toolbar button Resume toolbar button on the Flow Debug View. The next flow breakpoint that the execution encounters is now highlighted. WebSphere Message Broker supports the notion of reusable flows that can be nested within other flows. Click the Step Into Subflow toolbar button Step into Subflow toolbar button to step into a subflow. A new editor that contains the subflow is displayed. The Flow Stack is also updated to indicate that we are now debugging a subflow and the corresponding flow names are shown in the stack. To step over to the next connection, click the Step Over Node toolbar button Step Over Node toolbar button. Click the Step Out of Subflow toolbar button Step Out of Subflow toolbar button to return to the parent flow. Once the parent flow receives the focus, use the Run to Completion toolbar button Run to completion toolbar button to resume execution while ignoring the remaining breakpoints. This will run the flow until the end and the thread will be removed from the Flow Debug View.

Figure 3. Flow breakpoint Pops
Flow breakpoint Pops

Flow Debug Message View

Every time you pause at a breakpoint, the Flow Debug Message View shown below displays the content of the messageas it is being processed in the broker. You can expand this view and modify the value of the selected field. The modified value will be propagated to the broker and will take effect immediately.

Figure 4. Changing the message content
Changing the message content

Debugging Flows with Aggregate Nodes

Due to the complex nature of the Aggregate nodes, you should be aware of the following details when you debug flows that contain aggregates nodes:

  1. The AggregateReply node has to wait until it gets the reply from all the AggregrateRequest nodes before it continues with the message flow execution. Therefore, the user has to ensure that the timeout setting in AggregrateReply node is long enough to cover the time needed to step from AggregateRequest to AggregateReply nodes. If the timeout is reached, then the AggregateReply node will throw a timeout exception.
  2. The AggregrateReply node in processPurchaseOrderFlow is configured to receive two messages: one from each MQ input node. In WebSphere Message Broker, each message that is placed in an input queue will be represented by a thread in the Flow Debug View. In our example, if you set a breakpoint after each input node, two distinct threads will appear. Each thread will be used to deliver the message to the AggregateReply node and will then be terminated. One exception is that the last thread that delivers a message to the Aggregate Reply node will not be terminated and will be used to complete the flow execution. If the timeout is reached before the AggregateReply node receives all the messages, then a new timeout thread will appear instead.

Source debugging

WebSphere Message Broker V5.0 lets you debug source nodes such as Filter, Compute, Database, and Java plug-in. In this article, we will use ComputeTotalPriceofItems node and Send Email node in the processPurchaseOrderFlow flow to demonstrate how to debug both ESQL and Java code.

To ensure that your workbench is configured for source debugging, select Window => Preferences => Flow and check the preferences window. ESQL debugging is enabled by default.

Invoke source debugging

You can invoke source debugging while debugging flows in two ways:

  1. Click the Step into Source Code toolbar button Step into Source Code toolbar button in the Flow Debug View to step into the source code.
  2. Set a breakpoint in the source editor and invoke the flow by sending a message to the input queue. The Debug perspective displays.

Now, you can debug the source code using the Debug perspective.

Debugging with SQL

To demonstrate ESQL source debugging using the Step into Source approach:

  1. Right-click the connection to set a flow breakpoint before computeTotalPriceOfItems" as illustrated in Figure 5 below.
  2. Follow the steps in section "debugging details" to send a message to invoke the flow and when the execution stops at that breakpoint an indication that you can step into the source is shown above the node.
Figure 5. Stopping before a compute node
Stopping before a compute node

As soon as you click Step into Source Code in Flow Debug View, the perspective will switch to the Debug Perspective, and the execution will stop at the first line of the ESQL source code inside the ComputeTotalPriceOfItems node.

Figure 6. After Stepping into Computer ( ESQL) Node
After Stepping into Computer ( ESQL) Node

To add or remove source breakpoints, use the popup menu on the vertical ruler of your ESQL editor. It is important to notice that you can set breakpoints only on lines that contain valid statements. In this example, set a breakpoint on line 32 of CalculatePurchasePrice.esql as shown in Figure 7 below.

To control the execution of the source code, you can click the tool bar button (Resume, Step Into, Step Over, Step Return, and Terminate) on the Debug View. Click the Resume toolbar button and the execution will pause at the breakpoint on line 32.

Figure 7. After resuming from the first pause in ESQL
After Stepping into Computer ( ESQL) Node

While the execution is suspended, the Variables View displays ESQL variables defined in the ESQL code, as well as the input message, LocalEnviornment, Environment, output message, output LocalEnvironment, and outputExceptionList. To change the selected scalar variable value, select Change Variable Value from the popup menu of the Variable View. Important: Please notice that you cannot change the value of a reference variable.

To exit the source debugging and resume the flow debugging, click the Step Return toolbar button. This will resume the execution, and it will pause at the first connection following the current ESQL node. If you were to click Resume, the execution would stop at the next flow or source breakpoint. Once you return to flow debugging, click on Run to Completion to end this debug session.

Debugging Java plug-in nodes

  1. Configure the environment to enable debugging of Java plug-in nodes.
    1. Set the debug port number (any unused port) for the JVM in the broker by running the following command:
      mqsichangeproperties BROKER_NAME -e EXECUTIONGROUPNAME -o ComIbmJVMManager -n jvmDebugPort -v PORTNUMBER
    2. Restart the broker. Ensure that your JVM debug port has been correctly set by running the following DOS command: netstat --a, inspect the output and verify that the specified port is "LISTENING".
      Figure 8. Enable Debugging Java Plug-in Node
      After Stepping into Computer ( ESQL) Node
    3. From the "windows" menu, select "preferences", then click the "Flow Debug" to verify that the check box "enable java debugging" is checked. The Debug View in the Debug Perspective should contain a Remote Java application launcher as illustrated in Figure 8.
    4. Right-click on the message flow project, and select "properties" to verify that the message flow project containing the Java plug-in node has a project reference to the project containing the Java node implementation.
  2. Debugging Java source code
    1. Double-click the vertical ruler in Java editor to set a Java breakpoint. The Breakpoints View will display both ESQL and Java breakpoints.
    2. Click the toolbar button toolbar button to display only breakpoints supported by the selected target as in the example.
    3. Click the Remove All tool bar button in breakpoint view to remove all the ESQL breakpoint. Double-click on vertical ruler on line 48 to set a breakpoint on line 48 of SendEmailNode.Java as shown below and send a message to invoke the flow.

      Notice that a thread and a stack frame have been added in the Debug View, the Java editor is opened, and the line 48 is highlighted. The Variables View displays Java variables of the selected stack frame. Similar to the ESQL Variables View, you can change the selected variable value, and it will be updated immediately.

      Figure 9. Stopping at the ESQL Breakpoint
      Stopping at the ESQL Breakpoint
    4. From the Debug View, select either Resume, Step Into, Step Over, Step Return, or Terminate to control the execution of the source code.
    5. Use either the Step Return or Resume toolbar button as previously described in the ESQL debugging to resume flow debugging.
    6. Once you return to flow debugging, click Run to Completion to end this debug session.

Mapping debugging

Unlike ESQL or Java debugging where users can set breakpoints on the source code, the same action cannot be performed in the mapping editor. Instead, the user can step into a mapping node and step through every statement in a mapping routine to examine and monitor the changes of source data performed by the broker. WebSphere Message Broker provides mapping support in the following nodes: Mapping, DataInsert, DataUpdate, DataDelete, Extract, and Warehouse. Mapping debugging is enabled by default, and is control by the ESQL debugging preference. In this article, we are going to use the StorePurcahseOrder mapping node to illustrate how mapping debugging works.

  1. Right-click the connection to set a flow breakpoint before StorePurcahseOrder node as illustrated below in Figure 10.
  2. Send a message to invoke the flow (see the detail in section "debugging basics"), and the execution will pause at this breakpoint with the "Step Into Source Code" icon shown on top of the StorePurcahseOrder node.

    Figure 10. Before stepping into the Mapping node
    Before stepping into the Mapping node
  3. Click the Step Into Source Code toolbar button to debug the mapping routines defined within this node. The Debug Perspective will be activated, the mapping editor will open, and the mapping routine will be highlighted in both the mapping editor and Outline Pane.
  4. Select either of these debug actions (Resume, Step Into, Step Over, Step Return, and Terminate) on the Debug View to control the execution of the mapping.

The stack frame in Debug View shows the mapping routine being executed with mapping ESQL code fragments displayed. Upon clicking on the stack frame, the corresponding mapping routine and its source and target element will be highlighted in both the Outline Pane and inside the mapping editor. The Variables View, as described in the ESQL debugging section, contains all the related information including messages and variables. Users can modify the values for the ESQL variables in the Variables Pane exactly as shown in the ESQL debugging section.

Figure 11. Stopping at the map statement
Stopping at the map statement

To resume execution, you can click the Step over toolbar button in debug view to step over to the next ESQL statement or you can simply click on Step Return to resume Flow Debugging.


Conclusion

This article demonstrated some of the basic features of the WebSphere Message Broker Flow Debugger and described how you can take advantage of the more advanced debugging functionality within this product. Specifically, the integration of the flow debugger with the source debuggers enables you to debug your applications using any level of abstraction. Furthermore, the debugging is more intuitive since it is all orchestrated from one tool and thus makes it easy for you to track both the control and data flow of your application.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=95621
ArticleTitle=Integrating applications using WebSphere Message Broker: Part 6 -- Debugging message flows using Websphere Message Broker
publish-date=10042005