Use the Collector node to create message collections based on rules you configure in the node.
This topic contains the following sections:
A message collection comes into existence 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. An input terminal on the Collector node is able to receive a new message as soon as the last message to be received is added to a message collection.
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 2 messages from each input terminal, the message collection is complete when 2 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 collections are coordinated. You can enable the message collection to be automatically propagated for processing, or alternatively for the message collections to be propagated when a control messages is received.
You can also set an expiry timeout for message collections that fail to be completed in a satisfactory time, using a property on the Collector node. The timeout starts when the first message is added to a message collection. If the timeout expires without the message collection becoming 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 workbench by the following icon:
Look at the Collector node sample to see an example of how to use this node. You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
The Collector node has one static input terminal: Control, and four static output terminals: Out, Expired, 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, then any incomplete message collections are propagated to the Expired terminal.
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, then the transaction is caused to rollback. Messages in the message collection are backed out onto the Collector node's queue. The exception list is written to the system log. This step is repeated until the message collection is successfully processed. In order to avoid a situation where an exception in the flow causes the message collection to fail to be propagated successfully, ensure you connect the Catch terminal to a flow to handle any exceptions. Also ensure you set an expiry timeout to propagate incomplete message collections.
When you have put an instance of the Collector node into a message flow, you can configure it. For more information, see Configuring a message flow node. To display its properties, either double-click the node, or right-click the node and click Properties. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.
The following steps describe how to configure the Collector node:
The Collector node terminals are described in the following table.
Terminal | Description |
---|---|
Control | The static input terminal that accepts control messages. Any message received by the Control terminal is treated as a control message. |
Out | The output terminal to which the complete message collection is routed if the received messages satisfy the configured conditions for the message collection. |
Expired | The output terminal to which the incomplete message collection is routed if the received messages do not satisfy the configured conditions within the time specified on the Collection expiry property. If you have not set a value for the Collection expiry property this terminal is not used. |
Failure | The output terminal to which the message collection is routed if a failure is detected during processing. |
Catch | The output terminal to which the message collection is routed if an exception is thrown downstream and caught by this node. |
The Collector node can have further dynamic input terminals.
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:
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | The node type, Collector | The name of the node. |
Short Description | No | No | A brief description of the node. | |
Long Description | No | No | Text that describes the purpose of the node in the message flow. |
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:
Property | M | C | Default | Description |
---|---|---|---|---|
Terminal | Yes | No | The terminal name | This is not a property of the node, but a label to show the name of the dynamic input terminal. |
Quantity | Yes | No | 1 | This property specifies the number of messages that the input terminal accepts to add to a message collection. If you select Zero or choose to unset this property, there is no limit to the number of messages accepted. In this case the value set on the Timeout property must be greater than zero. |
Timeout | Yes | No | This property specifies the maximum time in seconds that the input terminal accepts messages for. If you select Zero or choose to unset this property, there is no limit on the time to wait for messages. In this case the value set on the Quantity property must be greater than zero. | |
Correlation path | No | No | This property specifies the path in the incoming message
from which to extract a value for the name for the correlation string. Messages
are grouped by the value from the correlation path. The correlation path is
defined using XPath. You can define your own correlation path using XPath,
or select from the following predefined paths:
|
|
Correlation pattern | No | No | This property specifies a pattern to match the contents of a correlation path value against. You must set the Correlation path property before you use the Correlation pattern property. If you set the correlation pattern, you must use one * character, optionally surrounded by other text. For example, *.dat. |
The remaining Basic properties for the Collector node are shown in the following table:
Property | M | C | Default | Description |
---|---|---|---|---|
Collection name | No | No | This property specifies the name of the message collection.
|
|
Collection expiry | No | Yes | 0 | The amount of time, in seconds, that the Collector node waits for messages to arrive. After this time an incomplete message collection is expired and propagated to the Expired output terminal. A warning is issued if this property is not set. |
Event coordination | Yes | No | Disabled | This property specifies how messages received on the
Control terminal for event coordination processing are handled in the Collector node.
|