Skip to content

Splitting Messages with Join

Note: It is recommended that the Neuron process documentation be reviewed before running this sample. The documentation thoroughly describes each process component individually and describes how to configure each one as well as how to construct a process and associate it with a Neuron Publisher or Subscriber. See the Configuration Notes section at the end of this document for more information.

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.

Figure 1: An empty Split process component as displayed in the Neuron Process designer.
Figure 2: The completed Split Orders – Wrapper process as displayed in the Neuron Process designer.
<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.

Note: The Split portion of the Split process step extracts each child message from the parent message. As each child message is extracted, it is forwarded to the process steps configured in the execution block of the Split process step. Upon successful processing of the first child message, the next child message is extracted from the parent and forwarded to the execution block. This is repeated until all child messages are processed. Once finished, the Join portion of the process step is executed.
Note: The Split process step has a property named Synchronous that controls how to process the messages that are split from the parent message. If this property is set to “True”, each messages is processed individually in the execution block on a single thread. The first message must complete before the second message is processed, etc. If this property is set to “False”, each message is processed asynchronously in the execution block on its own thread. Several threads are used during asynchronous processing.

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.

Figure 4: The code used for the “Code Split” step in the Split Orders – Code process.
Figure 5: The code used for the “Code Join” step in the Split Orders – Code process.

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.
Figure 6: OrderProcessor test client history tab showing 3 Order messages received.
  1. 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.
Figure 7: Orders test client history tab showing the joined Order message received.
  1. 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.
  2. Select OrderSplitter from the list of parties.
  3. Click on the Processes tab and then click the Edit Processes link as shown in Figure 8.
Figure 8: The Processes tab for the party OrderPublisher.
  1. In the Assign Processes dialog box, uncheck the currently configured process and check the process you wish to test next. See Figure 9.
Figure 9: The Assign Processes dialog for the party OrderSplitter.
  1. Click the Close button, then click the Apply button to apply the changes for the party OrderSplitter.
  2. Save the changes by clicking File->Save.
  3. 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.
Figure 10: The Neuron Process Designer’s Trace Window displaying each message split from the original message. This was accomplished by dragging a Trace step into the Steps execution block of the Split process.

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.

Figure 11: The Neuron Process Designer displaying the SplitOrders – Code process. Property Grid at the bottom right displaying the properties of Publish process step named “Send Order”. Note the topic that the step publishes on is “Orders.Processing”.
Was this article helpful?
Dislike 0
Previous: Retry Call to Web Service
Next: Splitting Messages with Null Join