WebSphere Message Brokers
File: ac37730_
Writer: Cerys Giddings

Task topic

This build: July 31, 2007 21:20:57

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 into each message collection 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 using the Collection Definition table, on the Basic tab of the Properties view.

To configure the event handler properties on the Collector node:

  1. Switch to the Broker Application Development perspective.
  2. Open the message flow with the Collector node.
  3. Right-click the Collector node and select Properties.
  4. Click on the Basic tab.
  5. 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 in 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 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. 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 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 that the selected input terminal accepts messages for, 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, then the message collection is propagated. 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 the terminals are added to the same message collection. For example, if you have set the Timeout to 10 seconds on input terminal A and 20 seconds on input terminal B, all the messages received on A during ten seconds are added to a message collection, and all the messages received on terminal B in twenty seconds are added to the same message collection. When the next message arrives on A or B, a new message collection is created and the timeout begins again.
      1. In the Collection Definition table, click in 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, 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.

      You must enter a value for Timeout.

    • 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, then 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 a * in the name of the message collection, it is replaced by the correlation string.
      1. In the Collection Definition table, click in the row for the selected input terminal within the Correlation path column.
      2. Either select a predefined correlation path from the drop-down list, or enter your own correlation path using XPath. For example, in the following message the correlation string is foo in the name field:
        <library>
        	<name>foo</name>
        	<more>
        		...
        	</more>
        </library>
        In this example, the correlation path using XPath is /library/name.

        The XPath root / is defined as the message body, and the variables $Root, $LocalEnvironment and $Environment are available to allow the path to start at the roots of the message, local environment and environment trees.

      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 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 in 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, then the unmatched message is added to a default unnamed message collection.

  6. Repeat step 5 for each of the input terminals that you added to your Collector node. You can configure different event handlers for different input sources.
Next: Configure the collection expiry.
Related concepts
Message flows overview
Related tasks
Configuring flows for message collection
Designing a message flow
Creating a message flow
Defining message flow content
Using control messages with the Collector node
Related reference
Collector node
Notices | Trademarks | Downloads | Library | Support | Feedback

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

ac37730_ This topic's URL is: