WebSphere Message Brokers
File: ac37820_
Writer: Cerys Giddings

Reference topic

This build: July 31, 2007 21:21:00

Collector node

Use the Collector node to create message collections based on rules you configure in the node.

This topic contains the following sections:

Purpose

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. You can use the Collector node to group messages from different sources into a message collection based on any or a combination of the following rules:
  • Number of messages
  • Collect messages for a set period of time
  • Match the contents of a correlation path
  • Match the contents against a correlation pattern
These rules are known as event handlers. You can configure event handler properties for each input terminal. You can use a mixture of event handlers for each input terminal, and use different event handlers for different input terminals. You use an XPath filter expression to match the contents of an input message against a correlation path or pattern. For more information about XPath 1.0 query syntax, see XPath.

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:

Collector node icon

Using this node in a message flow

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.

Use the Collector node to group together messages from different input sources for further processing. A message collection can be processed by the following nodes only:
  • Compute
  • JavaCompute
Errors might be generated if you try to process a message collection with a node that does not support message collections.

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.

Configuring the Collector node

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:

  1. Optional: On the Description tab, enter a short description, a long description, or both. You can also change the name of the node on this tab.
  2. On the Basic tab:
    1. Enter values for the event handler properties for each dynamic input terminal that you have added to the Collector node in the Collection Definition table.
      1. Enter a value for the Quantity. This value is used to specify the number of messages that this input terminal accepts and adds to a collection. The default value is 1; if you accept this default value, only one message is added to a collection. If a second message is received on the terminal, a new collection instance is created for it. 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. This property is mandatory; you must enter a value.
      2. Enter a Timeout value in seconds. This value is used to specify the maximum time in seconds that this input terminal accepts messages for. If you accept the default value Zero, the timeout is disabled and 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. This property is mandatory; you must enter a value.
      3. Enter a value for the Correlation path. This value is used to specify the path in the incoming message from which to extract a value for the correlation string. Messages are only accepted into a message collection if they have the same correlation string. Messages are grouped by the value from the correlation path. Define your own correlation path using XPath, or select from one of the predefined paths. If you define a value for Correlation path, you can optionally configure a Correlation pattern.
      4. Enter a value for the Correlation pattern. This value is used to specify a pattern to match the contents of a correlation path value against. You must set the Correlation path property before you set the value for Correlation pattern. If you set the correlation pattern, you must use one, and only one, * character, optionally surrounded by other text. For example, *.dat.
    2. Enter a value for Collection name. This value is used to specify the name of the message collection. If you set this property to contain the wildcard *, the wildcard is replaced by the correlation string from the relevant event handler. If you leave this property blank or use * and the correlation string is empty, then the collection name is set to an empty string.
    3. Enter a Collection expiry value in seconds. This value is used to specify 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. The default value is zero; if you accept this default value, the collection expiry is disabled and the Collector node waits for messages indefinitely. Set a value greater than zero to ensure that the message collection is processed, even if not all messages are received. A warning is issued if this property is not set.
    4. Enter a value for Event coordination. This value is used to specify how messages from the Control input terminal are handled for event coordination processing in the Collector node. The default value is Disabled; if you accept this default value, messages to the Control terminal are ignored and collections are propagated when they are complete. If you select All complete collections, complete message collections are held on a WebSphere MQ queue. When a message is received on the control terminal, all the complete message collections on the WebSphere MQ queue are propagated to the Out terminal. If you select First complete collection, complete message collections are held on a WebSphere MQ queue. When a message is received on the control terminal, the first complete message collection on the WebSphere MQ queue is propagated to the Out terminal. The collections are propagated in the same order that they become complete. If the WebSphere MQ queue is empty when the message is received on the Control terminal, then the next complete message collection is immediately propagated to the Out terminal. This property is mandatory.

Terminals and properties

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:
  • $Root/Properties/WildcardMatch
  • $Root/MQMD/CorrelID
  • $Root/FileInput/Name
  • $Root/JMSTransport/Transport_Folders/Header_Values/JMSCorrelationID
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.
  • If you set this property to contain the wildcard *, the wildcard is replaced by the correlation string from the relevant event handler.
  • If you leave this property blank or use * and the correlation string is empty, then the collection name is set to an empty string.
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.
  • If you select Disabled, messages to the Control terminal are ignored and collections are propagated when they are complete.
  • If you select All complete collections, complete message collections are held on a WebSphere MQ queue. When a message is received on the control terminal, all the message collections on the WebSphere MQ queue are propagated to the Out terminal.
  • If you select First complete collection, complete message collections are held on a WebSphere MQ queue. When a message is received on the control terminal, the first message collection on the WebSphere MQ queue is propagated to the Out terminal. If the WebSphere MQ queue is empty when the message is received on the Control terminal, then the next complete message collection is immediately propagated to the Out terminal.
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:00

ac37820_ This topic's URL is: