Splitting Messages with Join

Overview

This sample demonstrates how a Neuron Process can split a message into parts for processing and re-join those parts into a single message for further processing. A Message may contain multiple elements, each of which requires special processing. For example, a purchase order published to the bus may contain several individual orders that must be processed separately. Batch file processing is another common scenario which requires the ability to split and process the individual parts of the original message as separate distinct messages. Often, these individual messages are sent for processing using a request-reply message exchange pattern. The responses can be collected and joined together for either further processing or as a return message to the original sender.

This sample demonstrates how to use the Split process step to split a batch of orders into individual parts and how to re-join the individual orders into a single message.

Process Components Demonstrated:

• Split
• Publish

Solution

The Split Orders – Wrapper process depicted in Figure 2 begins with the Split portion of the Split process step. In this process step the message is split using an XPath expression into individual child messages.

<Orders>
  <Order>
    <OrderID>1234</OrderID>
    <OrderDate>4/22/09</OrderDate>
    <OrderAmount>100.00</OrderAmount>
  </Order>
  <Order>
    <OrderID>1235</OrderID>
    <OrderDate>4/22/09</OrderDate>
    <OrderAmount>110.00</OrderAmount>
  </Order>
  <Order>
    <OrderID>1236</OrderID>
    <OrderDate>4/22/09</OrderDate>
    <OrderAmount>120.00</OrderAmount>
  </Order>
<Orders>

<Order>
  <OrderID>1234</OrderID>
  <OrderDate>4/22/09</OrderDate>
  <OrderAmount>100.00</OrderAmount>   
</Order>

Figure 3: The original message (on the top) with the desired selection elements highlighted and an Order message that is the result of the split. An XPath expression of “Orders/Order” will select each Order block that is found under the root element of Orders.

Inside the Split process component is a process execution block named “Steps”. In this block any number of process steps can be specified. In this example there is a single Publish process step named “Send Order” in the execution block, which each child message is forwarded to.

The Publish process step publishes each child message to a topic as a new message. For example, if the original message (before being split) contained 10 orders, then 10 orders would be published to the topic configured for the Publish process step. In this example the Publish process step is configured to publish on the “Orders.Processing” topic.

The Join part of the Split process step receives each message part in sequence and reassembles the contents. A wrapper element tag as well as a namespace can be specified for the Join to use as a wrapper around the reassembled parts.

This example also includes the process Split Orders – Code. The steps used in this process are identical to the Split Orders – Wrapper process, except the Split and Join are both accomplished using the Code option. See Figures 4 & 5 for examples of how to use code in a split and join.

Running the Sample

Open the Sample

To open this sample, see the topic Using the Neuron Samples and select the Splitting Messages with Join sample.

Run the Sample

1. The sample launcher opens 3 Neuron Test Clients. Connect one client to the OrderSplitter party. Connect the second client to the OrderProcessor party. Connect the third client to the Orders party.
2. From the Repository tab in Neuron Explorer copy the test message OrdersTestMessage from the Xml Documents area. Paste the test message into the OrderSplitter test client’s Send tab message field.
3. Make sure that the topic “Orders” is selected in the Topic Dropdown located above the message field on the Send tab of the OrderSplitter test client.
4. Click the Send button on the test client connected to the OrderSplitter party and review the results in the History tab of the test client connected to the OrderProcessor party. Note that there are 3 Order messages received as shown in Figure 6 below.

5. Review the results in the History tab of the test client connected to the Orders party. Note the joined Order message received as shown in Figure 7 below.

6. To test the Split Orders – Code process you will need to configure the OrderSplitter party to use it. Go to the Messaging tab in Neuron Explorer and click on Publishers.
7. Select OrderSplitter from the list of parties.
8. Click on the Processes tab and then click the Edit Processes link as shown in Figure 8.

9. In the Assign Processes dialog box, uncheck the currently configured process and check the process you wish to test next. See Figure 9.

10. Click the Close button, then click the Apply button to apply the changes for the party OrderSplitter.
11. Save the changes by clicking File->Save.
12. Repeat steps 1 – 5 to test the Split Orders – Code process. Note – if you did not close the test client, you should disconnect and reconnect the OrderSplitter party in the test client to make sure the new process has loaded.
    
    Note: An Optional Trace process step can be added in the Steps execution block of the Split process step to write the output of each message to the Trace Window.

Configuration Notes

All processes with the exception of the Code process step are configured by selecting and setting their properties in the property grid located at the bottom right of the process designer. The Code process step is configured by selecting the “Edit” option from the short cut menu that is available when right-clicking the Code step in the process designer. See the process documentation for more information.