Resequence node

Use the Resequence node to control the sequence in which a group (or groups) of incoming messages are propagated in a message flow.

The Resequence node is available in the following operation modes:
  • Developer
  • Application Integration Suite
  • Standard
  • Advanced
For more information, see Operation modes.

Information about the state of in-flight messages is held on storage queues that are controlled by WebSphere® MQ, so you must install WebSphere MQ on the same computer as your integration node if you want to use the capabilities provided by the Resequence node. The storage queues that hold the state information are owned by the queue manager that is associated with the integration node, and you specify this queue manager by using the -q property of the mqsicreatebroker command. For more information about the queues that are required by the Resequence node, see Configuring the storage of events for Resequence nodes.

This topic contains the following sections:

Purpose

The Resequence node controls the sequence in which a group (or groups) of incoming messages are propagated through the node in a message flow.

You can use a Resequence node to rearrange groups of messages into sequential order according to a sequence number in the message. If the retry mechanism is Infinite (the default value), each message must contain a sequence number, which can be any positive or negative integer. If the retry mechanism is Failure, the sequence number can be omitted; see Retry mechanism, later in this topic. The sequence number is calculated by an XPath expression defined in the Path to sequence number property on the node, and it can be one that was added to the message by a Sequence node.

The Resequence node can reorder multiple sequence groups independently of each other, but it cannot reorder messages between sequence groups. The group to which a message belongs is determined by the properties of the Resequence node.

Each sequence group can be associated with only one Resequence node. Multiple Resequence nodes can have a sequence group with the same name, but each of those sequence groups is treated as a separate group. The combination of the integration server name, message flow name, node name, and sequence group name is used to differentiate between the sequence groups.

For example, you might have a message flow called flow1 containing a Resequence node called node1, which is deployed to an integration server called eg1. A message is sent to it using a sequence group called group1. The result is eg1/flow1/node1/group1. Exactly the same message flow in a different integration server, for example eg2, would result in eg2/flow1/node1/group1.

You can configure a Resequence node to use multiple threads for propagating messages, but only if each message that is being propagated belongs to a different sequence group. For messages belonging to the same sequence group, only one thread at a time can be used to propagate messages. As a result, the sequential order of messages in a sequence group is preserved, but no order between groups is maintained.

A transaction break occurs at the Resequence node. Messages arriving at the node are not directly propagated to the output terminal; all messages (including the next message in the sequence) are initially serialized to an internal WebSphere MQ queue. The storing of the message occurs in the current transaction; when it has been stored, the transaction is completed. If a stored message is the next one in the sequence, it is propagated down the message flow under a new transaction. Only the serializable part of the data is propagated from the node; local environment, environment, and exception lists are not preserved.

If the retry mechanism is Infinite, any exceptions that occur in nodes following the Resequence node are rolled back to the Catch terminal of the Resequence node. If the Catch terminal is not connected to any other nodes, the messages are re-delivered to the original terminal (Out, Missing, or Expired). The messages are never backed-out or discarded. If the retry mechanism is Failure, see Retry mechanism, later in this topic.

The Resequence node stores all received messages onto internal queues before propagating messages downstream, even when they are received in order. The message flow is effectively split into two running flows (one before the Resequence node and one after it. If the part of the message flow before the Resequence node runs significantly faster than the part of the message flow after it, the number of messages on the internal queue can increase more quickly than can be processed. Also, any expiry times given for end of groups or missing messages do not occur in a timely manner. When the queues are full, messages arriving at the Resequence node cause exceptions to be thrown. You can avoid this problem by following these steps:
  1. Ensure that the controlling applications send only a finite amount of work at a time, which the message flow can manage.
  2. Configure additional instances so that the second part of the message flow has more instances to do work with on. Use the properties on the Instances tab to give the Resequence node its own set of additional instances.
  3. Structure the message flow so that the part of the flow that places the most demands on the CPU (transformation, for example), comes before the Resequence node.
  4. If the large workload is transient, increase the maximum queue depth on the internal queues.
  5. Use the Resequence configurable service to partition the queues. This can prevent the situation in which an instance of the Resequence node fills up the queues and stops another instance working.

For information about the various states and state transitions of the Resequence node, see Resequence node state machines.

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

Resequence node icon

Terminals and properties

The terminals of the Resequence node are described in the following table.

Terminal Description
In The input terminal through which the incoming message assembly arrives at the node.
Failure The output terminal to which the incoming message is routed in the following situations:
  • If the incoming message cannot be accepted by the node, for example, if the sequence number is invalid. If the incoming message cannot be accepted, an exception list that provides error information is also propagated to this terminal.
  • If the retry mechanism is Failure and a message fails to propagate to the Out and Catch terminals. For more information, see Retry mechanism, later in this topic.
Out The output terminal to which the output message is propagated by default.
Expire The output terminal to which the message is routed if a timeout occurs while the node is waiting for the message to arrive. All subsequent messages in the same group are also propagated to this terminal.
Missing The output terminal to which the missing message (which caused a timeout to occur) is routed if it subsequently arrives at the node.
Catch The output terminal to which the message is routed if an exception is issued downstream and caught by this node. Exceptions are caught only if this terminal is attached.

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 for deployment).

The Description properties of the Resequence node are described in the following table.

Property M C Default Description
Node name No No Resequence 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 Basic properties of the Resequence node are described in the following table.

Property M C Default Description
Path to sequence number Yes No   An XPath expression that calculates the sequence number of the message.
Path to sequence group identifier No No   An XPath expression that calculates the sequence group identifier. Messages that have the same group identifier are considered part of the same sequence group. This property functions in the same way as the Correlation path property in the Collector node.
Start of sequence definition Yes No Literal, 0 Specifies the first sequence number in each group. Valid values are:
  • Literal and number
  • Predicate and XPath
  • Automatic and time in seconds
If this property is set to Automatic, the associated time is overridden by the value of the startSequenceSeconds property, if set, in the Resequence configurable service.
End of sequence definition Yes No Automatic Specifies when each sequence group has been completed. Valid values are:
  • Literal and number
  • Predicate and XPath
  • Automatic and time in seconds
If this property is set to Automatic, the associated time is overridden by the value of the endSequenceSeconds property, if set, in the Resequence configurable service.
Missing message timeout (seconds) No No   Specifies how long (in seconds) the node waits for the next message in the sequence before it moves on to the following one. This property is overridden by the Missing message timeout property, if set, in the Resequence configurable service.
The Advanced properties of the Resequence node are described in the following table.
Property M C Default Description
Persistence mode Yes No Non-persistent Specifies whether to store incomplete sequences of messages persistently. Valid options are:
  • Non-persistent
  • Persistent
Configurable service No Yes None set This property specifies the name of a Resequence configurable service to be used by the Resequence node.

The properties set by the Resequence configurable service override the equivalent properties set on the Resequence node.

For more information about the properties than you can set with this configurable service, see Configurable services properties.
The Retry properties of the Resequence node are described in the following table.
Property M C Default Description
Retry mechanism Yes No Infinite Specifies how the Resequence node handles a flow failure. Valid options are as follows:
  • Infinite
  • Failure

    The Failure option is valid only if the endOfSequence parameter is set to automatic, with a timeout value.

The behavior for the default setting of Infinite is described earlier, in Purpose.

If the Failure option is selected, behavior is as follows:

  • If a message fails to propagate to the Out and Catch terminals, the message is propagated to the Failure terminal. The Resequence node is returned to a state where it is waiting for that failing message, identified by its sequence number, to arrive again. Any subsequent messages in the sequence that have already been received are not sent out until the message that failed is resent to the node. Any subsequent messages in the sequence that arrive are held as usual.
  • If the Resequence node fails to find a sequence number (the XPath fails to resolve to an element), a sequence number is assigned. This number is the high-watermark + 1. For example, if messages 1 and 3 were processed, the next blank message is assigned the number 4.
  • The original exception list from the propagation failure is preserved.
The Instances properties of the Resequence node are described in the following table. For a full description of these properties, see Configurable properties in a BAR file.
Property M C Default Description
Additional instances pool No Yes Use Pool Associated with Message Flow The pool from which additional instances are obtained.
  • If you select Use Pool Associated with Message Flow, additional instances are obtained from the message flow pool.
  • If you select Use Pool Associated with Node, additional instances are allocated from the node's additional instances based on the number specified in the Additional instances property.
Additional instances No Yes 0 The number of additional instances that the node can start if the Additional instances pool property is set to Use Pool Associated with Node.
The Monitoring properties of the node are described in the following table.
Property M C Default Description
Events No No None Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.
You cannot use monitoring properties to configure transaction events on the following nodes: Use a monitoring profile instead; see Configuring monitoring event sources by using a monitoring profile.