IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Setting event handler properties

You can configure event handler properties for each dynamic input terminal on a Collector node. These event handler properties determine how the messages received by each terminal are added to message collections.

Before you start:

To complete this task, you must have completed the following tasks:

You can use one or more of the event handler properties to control the way that messages are added to message collections for each input terminal that you added to the Collector node. Incomplete message collections are stored on a WebSphere® MQ queue. The message collections are stored in the order that they are generated by the Collector node (first in, first out). Each message collection has an event handler instance for each of the input terminals. The event handler determines whether an incoming message on that terminal is added to a message collection. The event handler instance maintains information about the state of the collection, the number of messages received, the timer, and the correlation string. When a new message is received on an input terminal, it is offered to the event handler for each message collection waiting on the queue in turn. When the message is accepted by one of the event handlers, it is added to the message collection. The accepted message is not offered to any other message collections. If all the event handlers reject the message, it is added to a new message collection, which is added to the end of the queue.

The first message accepted into a collection determines the correlation string for that message collection, if it is configured. Subsequent messages offered to that message collection are only accepted if their correlation string matches that of the collection. The first message accepted by each event handler starts the timeout timer, if it is configured. Each message accepted by each event handler increments the quantity count. An event handler becomes satisfied when the number of messages accepted equals the configured quantity, or when the timeout value is reached. When an event handler is satisfied, the event handler does not accept any more messages. A message collection is complete only when all of the message collection's event handlers are satisfied. The message collection is then ready for propagation.

You can configure the event handler properties by using the Collection Definition table, on the Basic tab of the Properties view.

To configure the event handler properties on the Collector node:

Open the message flow with the Collector node.
Right-click the Collector node and select Properties.
Click the Basic tab.
Use the following instructions to configure the event handler properties that you want to set for each input terminal:
- If you want to add a set number of messages to each message collection from one or more of the terminals, you must enter a value for Quantity in the Collection Definition table. This value is used to specify the number of messages that each configured input terminal accepts to complete a collection. For example, if you have set Quantity to wait for 2 messages on three of the input terminals, the message collection is not complete until 2 messages have been received on each of the three input terminals. The complete message collection contains 6 messages, 2 from each of the three terminals. As soon as more than 2 messages are received on one of the input terminals, the next message is added to a new message collection.
  1. In the Collection Definition table, click the row for the selected input terminal within the Quantity column.
  2. Enter a value for the number of input messages that you want to add to a message collection. If you select Zero or choose not to set 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. If you accept the default value of 1; only one message from the selected terminal is added to a collection.
  You must enter a value for Quantity if Timeout is not set.
- If you want to collect messages for a set amount of time before the message collection is propagated you must enter a value for Timeout. This value is used to specify the maximum time in seconds for which the selected input terminal accepts messages before completing a message collection. The timeout interval starts when the first message has arrived at the selected terminal. Any subsequent messages are added to the same message collection. When the timeout interval ends, no more messages are added to the message collection from this terminal. When the conditions on all the terminals are satisfied, the message collection is ready for propagation. When the next message reaches the selected input terminal, a new message collection is created and the timeout interval starts again. If a timeout is set on multiple input terminals, each terminal collects messages for the configured amount of time. During the timeout messages from all of the terminals are added to the same message collection.
  1. In the Collection Definition table, click the row for the selected input terminal within the Timeout column.
  2. Enter a value for the length of time in seconds that you want to wait to add messages to a message collection. For example, to wait for messages to add to a message collection for an hour, enter a value of 3600. If you accept the default value Zero, timeout is not enabled 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.
  You must enter a value for Timeout if Quantity is not set.
- If you want to add messages to different message collections based on the content of the message you must enter an XPath value for the Correlation path. This value is used to specify the path in the incoming message from which to extract the correlation string. The correlation string is the value that is extracted by the correlation path. If a correlation pattern is specified, the correlation string is matched against the correlation pattern. Messages are only accepted into a message collection with the same correlation string. If you specify an asterisk (*) in the name of the message collection, it is replaced by the correlation string.
  1. In the Collection Definition table, click the row for the selected input terminal within the Correlation path column.
  2. Either select a predefined correlation path from the list, or enter your own correlation path using XPath. The correlation path must begin with a correlation name, which can be followed by zero or more path fields. For example, in the following message the correlation string is xxx in the name field:
```
<library>
	<name>xxx</name>
	<more>
		...
	</more>
</library>
```
    In this example, the correlation path using XPath is $Body/library/name.
    The variables $Root, $LocalEnvironment, and $Environment are available to allow the path to start at the roots of the message, local environment, environment trees, and message body.
  If the correlation path evaluates to an empty string the unmatched message is added to a default unnamed message collection.
  
  If you define a value for Correlation path, you can optionally configure a Correlation pattern.
- If you want to match a substring of the message content from the Correlation path, you can define a pattern to match in the message by using Correlation pattern. The Correlation pattern contains a single wildcard character and optional text. The correlation string, used for the name of the message collection, is the part of the substring that matches the wildcard. For example, if the correlation path contains the filename part1.dat in a file header, and the correlation pattern is specified as *.dat, the correlation string is part1.
  If this property is set, only messages that have the same correlation string are added to the same message collection. The first message added to a message collection determines the correlation string that must be matched by all other messages in that message collection.
  1. In the Collection Definition table, click the row for the selected input terminal within the Correlation pattern column.
  2. Enter a value for the correlation pattern. The Correlation pattern must contain a single wildcard character: *. This wildcard character can optionally be surrounded by other text.
  If the correlation pattern fails to match the wildcard to a substring, the unmatched message is added to a default unnamed message collection.
Repeat step 4 for each of the input terminals that you added to your Collector node. You can configure different event handlers for different input sources.

Note: Ensure that you set the event handler properties across different terminals carefully to match the expected delivery of messages to the terminals on the Collector node.

You can now configure the collection expiry, see Setting the collection expiry.

ac37730_.htm |

Last updated Friday, 21 July 2017