Collector node

Use the Collector node to create a message collection from one or more sources based on configurable criteria. For example, you might need to extract, combine, and transform information from three different sources. The messages from these different sources might arrive at the input terminals at different times and in an unknown order. A collection is defined by configuring an event handler for each input terminal. Each event handler controls the acceptance of a message into a collection according to the following properties:

• Number of messages
• Collect messages for a set period
• Match the contents of a correlation path
• Match the contents against a correlation pattern

The correlation properties allow collections to be made according to the content of the messages. The content is specified by using an XPath expression. The Collector node ensures that each collection contains an identical correlation string across all its inputs. For more information about XPath 1.0 query syntax, see W3C XPath 1.0 Specification.

A message collection is created when the first message arrives at any of the dynamic input terminals on the Collector node. Message collections are stored on a WebSphere® MQ queue.

When the conditions set by the event handlers for a message collection have been met, the message collection is complete and ready to be propagated. For example, if you set the event handlers on the Collector node to wait for two messages from each input terminal, the message collection is complete when two messages have been received by every terminal. When the next message arrives on an input terminal, it is added to a new message collection. You can select from a number of options to determine how the propagation of the message collection is coordinated. You can specify that the message collection is propagated automatically for processing, or alternatively that the message collection is propagated when a control message is received.

You can also set an expiry timeout for message collections that fail to be completed in a satisfactory time by using a property on the Collector node. The timeout starts when the first message is added to a message collection. If the timeout expires before the message collection is complete, the incomplete message collection is propagated to the Expire terminal. Set a value for the collection expiry to ensure that incomplete message collections do not remain stored on a queue indefinitely. Add appropriate processing to your message flow to handle incomplete message collections.

The Collector node is contained in the Routing drawer of the message flow node palette, and is represented in the IBM® Integration Toolkit by the following icon:

You can view information about samples only when you use the product documentation that is integrated with the IBM Integration Toolkit or the online product documentation. You can run samples only when you use the product documentation that is integrated with the IBM Integration Toolkit.

The Collector node has one static input terminal, Control, and four static output terminals: Out, Expire, Failure and Catch. These static terminals are always present on the node. In addition to the static input and output terminals, you can add dynamic input terminals for each input source that you want to use with the Collector node.

You can add and configure as many input terminals as required to the Collector node. You can configure the properties of each input terminal separately to control how the messages received on each input terminal are added to the appropriate message collection.

You can use the Control terminal to trigger the output of completed message collections from the Collector node. Configure the Event coordination property to set the behavior of the Collector node when messages are received on the Control terminal.

When a message collection is successfully completed, it is ready to be propagated to the Out terminal. If a value greater than zero is set on the Collection expiry property, any incomplete message collections are propagated to the Expire terminal.

Note: All input messages that are received under sync point from a transaction or thread by the Collector node are stored in internal queues. Storing the input messages under sync point ensures that the messages remain in a consistent state for the outgoing thread to process; such messages are available only at the end of the transaction or thread that propagates the input messages. If a transaction propagates more than one input message for the Collector node, the Collector node does not behave as expected.

Consider the following message flow:

If the Compute node propagates more than one message under sync point to the input terminal of the Collector node, the Collector node cannot create a message collection until the incoming transaction ends. In such a scenario, consider splitting the message flow into 2 flows that use an intermediate WebSphere MQ queue to temporarily store the messages, as follows:

A new transaction is created when a message collection is complete, and is propagated to the next node. Any exceptions that are caught from downstream nodes cause the message collection to be propagated to the Catch terminal on the Collector node, together with the exception list. If the Catch terminal is not connected to any other nodes, the transaction is caused to roll back. Messages in the message collection are backed out onto the queue of the Collector node. The exception list is written to the system log. This step is repeated until the message collection is successfully processed. To avoid an exception that causes the message collection to fail to be propagated successfully, ensure that you connect the Catch terminal to a flow to handle any exceptions. Also, ensure that you set an expiry timeout to propagate incomplete message collections.

If you use additional instances of a message flow or multiple inputs to the Collector node, you can use the Correlation path and Correlation pattern properties to ensure that related messages are added to the same message collection. If you use additional instances, or multiple inputs to the Collector node the order of messages in the message collection can be unpredictable. The order of messages is also unpredictable if you use WebSphere MQ cluster queues as inputs to the Collector node.

When you have put an instance of the Collector node into a message flow, you can configure it; see Configuring the Collector node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those properties that do not have a default value defined) are marked with an asterisk.

The Collector node terminals are described in the following table.

The Collector node can have further dynamic input terminals. You can create numeric terminal labels for the Collector node; however, the Compute node does not support numeric labels. Therefore, when you are defining a custom terminal for the Collector node, ensure that the name begins with an alphabetic character.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The Collector node Description properties are described in the following table:

The Collector node has two types of Basic properties. You can set properties for each dynamic input terminal that you add to the Collector node in the Collection Definition table in the Basic properties. The properties in the Collection Definition table define the event handlers for the messages arriving on the individual input terminals. The properties that you can set for each of the dynamic input terminals are described in the following table:

The remaining Basic properties for the Collector node are shown in the following table:

The Collector node Advanced properties are described in the following table: