See information about the latest product version
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.
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. Each message must contain a sequence number, which can be any positive or negative integer. 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 execution group 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 execution group 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 execution group, 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.
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.
- Ensure that the controlling applications send only a finite amount of work at a time, which the message flow can manage.
- 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.
- 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.
- If the large workload is transient, increase the maximum queue depth on the internal queues.
- 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 WebSphere Message Broker Toolkit by the following icon:
Using the Resequence node in a message flow
You can view information about samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit or the online information center. You can run samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit.
Configuring the Resequence node
When you have put an instance of the Resequence node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.
All mandatory properties that do not have a default value defined are marked with an asterisk.
Configure the Resequence node:
- Optional: On the Description tab, enter a Short description, a Long description, or both. You can also rename the node on this tab.
- On the Basic tab, set the properties that
determine how the message sequence is controlled.
- Use the Path to sequence number property to specify an XPath expression that is used to calculate the sequence number of the message. The XPath expression can calculate the sequence number or it can point to an integer field in the message. Messages can also contain an optional sequence group identifier. This property is mandatory.
- Use the Path to sequence group identifier property to specify the location of the sequence group identifier. The location is specified as an XPath expression. Messages that have the same group identifier are considered part of the same sequence group.
- Use the Start of sequence definition property
to identify the first sequence number in each group.
- Select Literal to specify a literal sequence number, which can be any positive or negative numeric value. When the message with the specified sequence number arrives, the messages are propagated.
- Select Predicate to
specify an XPath expression that evaluates to either True or False, indicating whether the
message is the first in the sequence.
Messages continue to be collected while the expression evaluates to False. When the expression of a message is evaluated to True, it indicates that the message is the first in the sequence.
Typically, the XPath expression evaluates to a Boolean; however, if other data types are returned, the predicate is determined in the following way:Table 1. Returned data type True False Boolean True False Numeric Any non-zero value 0 or 0.0 String Any string matching true (case-insensitive) Any string not matching true (case insensitive) NodeSet Never Always When a message evaluates the expression to True (and is therefore identified as the start of the sequence), the node checks that the message has the smallest sequence number collected up to that point. If messages are found with lower sequence numbers, an exception is thrown.
When the first message that evaluates to true has been processed successfully, the XPath expressions of subsequent messages are not checked. If a message arrives with a lower sequence number than the message that was identified as the start of the sequence, an exception is thrown.
- Select Automatic to specify a time limit for gathering messages before using the lowest numbered message.
- Use the End of sequence definition property
to specify when each sequence group has been completed.
- Select Literal to specify a literal sequence number. This value can be any positive or negative numeric value that is equal to or greater than the value of the Start of sequence definition property. When the message with the specified sequence number arrives, the sequence group remains open and waits for missing messages until the Missing message timeout property expires. Any messages that arrive within that time are included in the group (unless they are duplicates or outside the allowed range) until the sequence group is closed. When the sequence group is closed, any new messages arriving for that group are treated as belonging to a new instance of the group.
- Select Predicate to
specify an XPath expression that evaluates to either True or False, to indicate whether the
message is the last in the sequence.
Typically, the XPath expression evaluates to a Boolean; however, if other data types are returned, the predicate is determined in the way shown in Table 1.
When the predicate evaluates to True, the sequence number of the message is assigned to the End of sequence definition property.
When a message has been received with the end of sequence predicate set to True, the sequence group remains open and waits for missing messages until the Missing message timeout property expires. Any messages that arrive within that time are included in the group (unless they are duplicates or outside the allowed range) until the sequence group is closed. When the sequence group is closed, any new messages arriving for that group are treated as belonging to a new instance of the group.
If a message arrives with the end of sequence predicate set to True and with a lower sequence number than a message that has already arrived, an exception is thrown.
- Select Automatic to specify the timeout period for the node. This option specifies how long (in seconds) the node waits for messages to arrive in an empty queue, before closing the sequence group. This option is useful for applications that cannot determine the final number in the sequence. The timer starts when there are no messages in the queue waiting to be propagated. If new messages arrive before the timeout period is reached, the timer is canceled. If no new messages arrive before the end of the specified time, the sequence group is closed and any further messages for the group are considered part of a new group.
- Use the Missing message timeout property
to specify how long (in seconds) the node waits for the next message
in the sequence before it moves on to the next message in the sequence.
Messages that arrive within the specified time limit are propagated
in sequential order to the Out terminal.
When the specified time limit has been exceeded, the messages are propagated in sequential order to the Expire terminal. Subsequent messages in the sequence group are also routed to the Expire terminal. If the missing message eventually arrives, it is propagated to the Missing terminal.
- On the Advanced tab:
- Use the Persistence mode property to specify whether to store incomplete sequences of messages persistently.
- Use the Configurable service property to specify the name of a Resequence configurable service that overrides specified properties of the Resequence node.
- Optional: On the Instances tab, set values
for the properties that show the additional instances (threads) that
are available for a node.
Multiple threads can be used to propagate messages from the same Resequence node, 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.
For more information about specifying additional instances, see Configurable message flow properties.
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 if the 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. |
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:
|
End of sequence definition | Yes | No | Automatic | Specifies when each sequence group has been
completed. Valid values are:
|
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. |
Property | M | C | Default | Description |
---|---|---|---|---|
Additional instances pool | No | Yes | Use Pool Associated with Message Flow | The pool from which additional instances are
obtained.
|
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 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:
|
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. |
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 using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |