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.
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.
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.
- 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. - Open the Flow Debug Perspective and click on the Attach To Flow Engine toolbar button
. - 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. - Invoke the flow.
- Select File => New => Message Enqueue File to create an enqueue file.
- Give a name to enqueue. This article uses the name: SampleTestMessage.enqueue.
- In the editor, specify the Queue Manager name: WEBOQMGR and the Input Queue Name: ORDER.REQUEST.Q00
- 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.
- Click the Write to Queue button to submit the message to the flow.
You can use this section to debug your message flows.
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
Figure 2. Flow breakpoint
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:
- The Thread ID, 2668 in this case, represents the thread that processes the input message through the flow.
- 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.
To resume the flow execution, click the 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 
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 
. Click the 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 
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
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
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:
- 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.
- 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.
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.
You can invoke source debugging while debugging flows in two ways:
- Click the Step into Source Code toolbar button
in the Flow Debug View to step into the source code.
- 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.
To demonstrate ESQL source debugging using the Step into Source approach:
- Right-click the connection to set a flow breakpoint before computeTotalPriceOfItems" as illustrated in Figure 5 below.
- 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
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
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
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.
- Configure the environment to enable debugging of Java plug-in nodes.
- 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 - 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
- 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.
- 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.
- Debugging Java source code
- Double-click the vertical ruler in Java editor to set a Java breakpoint. The Breakpoints View will display both ESQL and Java breakpoints.
- Click the toolbar button
to display only breakpoints supported by the selected target as in the example. - 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
- From the Debug View, select either Resume, Step Into, Step Over, Step Return, or Terminate to control the execution of the source code.
- Use either the Step Return or Resume toolbar button as previously described in the ESQL debugging to resume flow debugging.
- Once you return to flow debugging, click Run to Completion to end this debug session.
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.
- Right-click the connection to set a flow breakpoint before StorePurcahseOrder node as illustrated below in Figure 10.
- 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
- 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.
- 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
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.
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.
Learn
- Part 1: Integration scenario for creating a Web order processing application
- Part 2: Message set development
- Part 3A: Using message flows to integrate applications
- Part 3B: Using ESQL to develop message flow applications
- Part 4: Message Transformation using Message Broker mappings
- Part 5: Custom message flow node development
- developerWorks WebSphere Business Integration zone: Find more resources for WebSphere Message Broker developers.
Get products and technologies
Discuss
- Participate in the discussion forum.
- WebSphere Business Integration forum
- developerWorks blogs: Get involved in the developerWorks community.
Shu Tan is a staff software developer at IBM Toronto Laboratory in the Toronto, Ontario. She works on the debugger for Websphere Message Broker.
Comments (Undergoing maintenance)
Table of contents
Next steps from IBM
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
