Start of change
WebSphere Message Brokers
File: ac37370_
Writer: Karen Cameron

Reference topic

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

Route node

Use the Route node to direct messages that meet certain criteria down different paths of a message flow.

This topic contains the following sections:

Purpose

As an example, you might need to forward a message to different service providers, based on the request details. You can also use the Route node to bypass unnecessary steps. For example, you can check to see if certain data is in a message, and perform a database lookup operation only if the data is missing. If you set the Distribution Mode property to All, you can trigger multiple events that each require different conditions. For example, you could log requests that relate to a particular account identifier, and send requests that relate to a particular product to be audited.

You use XPath filter expressions to control processing. For more information about XPath 1.0 query syntax, see XPath.

The Route node is contained in the Routing drawer of the message flow node palette, and is represented in the workbench by the following icon:

Route node icon

Using this node in a message flow

The Route node has one input terminal and a minimum of three output terminals: Match, Default, and Failure. The Default and Failure output terminals are static, so they are always present on the node. The dynamic Match terminal is created automatically each time a new Route node is selected and used in the Message Flow editor. This behavior means that you do not need to always create this node's first dynamic output terminal, which is the minimum number of terminals needed for this node to operate. You can rename this dynamic terminal if "Match" is not an appropriate name.

A message is copied to the Default terminal if none of the filter expressions are true. If an exception occurs during filtering, the message is propagated to the Failure terminal. The Route node can define one or more dynamic output terminals. For all terminals, the associated filter expression is applied to the input message and if the result is true, a copy of the message is routed to the given terminal.

Each filter expression is applied to the input message in the order that is given in the filter table. If the result is true, a copy of the message is routed to its associated dynamic output terminal. If you set the Distribution Mode property to First, application of all filter expressions might not occur.

Consider the following example input message:
<EmployeeRecord>
	<EmployeeNumber>00001</EmployeeNumber>
	<FamilyName>Smith</FamilyName>
	<Wage>20000</Wage>
</EmployeeRecord>
and the following XPath filter expressions:
$Body/EmployeeRecord/EmployeeNumber="00002"|Match
$Body/EmployeeRecord/EmployeeNumber="00001"|out_exp2

In this example, the Distribution Mode property is set to First. The Route node processes the XPath filter expressions, in the order in which they appear, against the input message. Because the Distribution Mode property is set to First, the unmodified input message is propagated only once to the dynamic output terminal that is mapped to the first filter expression that resolves to true. In the example above, the first filter expression, which is associated with the Match terminal, is false because the employee number in the input message is not "00002". So no message is propagated to the Match terminal. The second filter expression is true, so a copy of the input message is routed to the "out_expr2" dynamic terminal. If the employee number in the input message were "00003", and therefore did not match either filter expression, the message would be propagated to the static Default output terminal. If the Distribution Mode property were set to All for this example, the same outcome would be achieved because only one filter expression was true.

Configuring the Route node

When you have put an instance of the Route node into a message flow, you can configure it. For more information, see Configuring a message flow node. Depending on the preferences that you have set, you can view the node's properties in the Properties view below the Message Flow editor or in the Properties dialog box. Either click the Properties view tab, 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.

Terminals and properties

The Route node terminals are described in the following table.

Terminal Description
In The static input terminal that accepts a message for processing by the node.
Match The dynamic output terminal to which the original message is routed when processing completes successfully.
Default The static output terminal to which the message is routed if no filter expression resolves to true.
Failure The static output terminal to which the message is routed if a failure is detected during processing.

The Route node can have further dynamic output terminals. Not all dynamic output terminals that are created on a Route node need to be mapped to an expression in the filter table. For unmapped dynamic output terminals, messages are never propagated to them. Several expressions can map to the same single dynamic output terminal. There is no static output terminal to which the message is passed straight through.

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 Route node Description properties are described in the following table.
Property M C Default Description
Node name No No The node type, Route 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 Route node Basic properties are described in the following table.
Property M C Default Description
Filters Yes No   A table where all rows are expressions and associated terminal names that define the switching that is performed by this node following evaluation of each filter expression. The full expression is in the format
XPath filter expression, terminal name	
All XPath expressions must start with $Root, $Body, or $LocalEnvironment. Expressions are evaluated in the order in which they appear in the table. To improve performance, specify the expressions that are satisfied most frequently at the top of the filter table. Typically, you specify a unique terminal name for each XPath expression.
Distribution Mode No Yes All This property determines the routing behavior of the node when an inbound message matches multiple filter expressions. If you set the Distribution Mode property to First, the message is propagated to the associated output terminal of the first expression in the table that resolves to true. If you set this property to All, the message is propagated to the associated output terminal for each and every expression in the table that resolves to true. If no output terminal matches, the message is propagated to the Default terminal.
Related concepts
Message flows overview
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:49

ac37370_ This topic's URL is:
End of change