Dynamic Router

The Dynamic Router communication point (also known as the dynamic router) provides an alternative mechanism to cross-route connectors for connecting routes together in Rhapsody, and for routing messages between lockers (using dynamic routers is the only way to transfer messages between lockers). Instead of explicitly wiring cross-route connectors between filters, a set of dynamic routers can be used to statically or dynamically route messages.

A Dynamic Router communication point may operate as an input or output dynamic router, in other words in either input or output mode, respectively. In output mode, a Dynamic Router communication point is capable of sending messages to another dynamic router running in input mode. The destination can be either configured statically in the configuration properties, or can be set dynamically using the router:Destination message property. Once the destinations have been identified, the message is moved directly to those input communication point queues without any need to re-persist the message. In input mode, a dynamic router only receives messages sent to it by other output mode dynamic routers.

The Rhapsody engine and Management Console maintain the path of a message that passes through Dynamic Router communication points. When viewed from the Management Console, a message has numerous events as it passes from component to component. When these events cross the boundaries of routes, Message View only displays those events for the component searched on, up until the route boundary (the last output node). The Dynamic Router communication point extends these message view boundaries and seamlessly ties together independent routes by displaying an inclusive message view path. Although the Cross Route connector offers a similar view, the advantage of the Dynamic Router communication point is that routes can be modularized and made truly independent from one another, thereby easing configuration design patterns and maintenance.

Message definitions are not preserved across lockers. When a message crosses a locker boundary via a dynamic router, the definition the message was parsed within the upstream route in one locker is not available in the downstream route in another locker. The message is therefore re-parsed with the definition associated with the downstream route.

Supported Operational Modes: Input, Output

Message View

You can use the Dynamic Router communication point to send a message from a route in one locker to a route in another. You can see a new message event in the Message View page with a:

• Forward link - if the message path continues to another locker. You can only select this link only if you have access to the target locker.
• Backward link - if the message path comes from another locker. You can only select this link only if you have access to the source locker.

The following screenshot displays the logical route boundaries in a single message view search result. This would previously have required three independent searches to form a view of a message's path as the message traversed across routes.

Path View

If a Dynamic Router communication point statically references another route, this route and its connections are also shown in path view, with a connection between the two routes:

If either the destination or delivery location is in a locker which is not visible to the user, then a locker icon is used in either the input or output (or both) sides to indicate this connection.

Input Mode Properties

Target names provide an alternative way to identify an input Dynamic Router communication point in a manner that is resilient to component or folder renames. There is no requirement for configured target names to be unique; if multiple input Dynamic Router communication points are configured to use the same target name then they all receive all the messages. However, it is possible to configure a Dynamic Router communication point to indicate that it expects that its target name to be unique. Unique target names are enforced at configuration time:

• An input Dynamic Router communication point expecting a unique target name fails to configure if another Dynamic Router communication point has already registered that target name.
• Any input Dynamic Router communication point fails to configure if another Dynamic Router communication point has already registered the desired target name as unique.

In both cases, it is the second (and subsequent) communication point to be configured that raises the configuration error.

Unlike other communication points, the Dynamic Router communication point does not need to be started when operating in input mode. This is because it never receives any messages from an external source, and messages are transmitted to it from an output Dynamic Router communication point by directly inserting those messages into its input queue. Consequently, starting the input Dynamic Router communication point is not necessary as it does not receive the messages itself (and of no negative consequence).

Disabled Notifications

The Long Idle Time and Unconnected Running Communication Point notifications are never be raised by a Dynamic Router communication point running in input mode. This is because the communication point never receives any messages from an external source, and messages are transmitted to it from an output Dynamic Router communication point by directly inserting those messages into its input queue. Consequently, it never has a real connection which can be tested for idleness. Thus, the communication point is internally configured not to raise these notifications while running in input mode.

Input Throttling Unavailable

Input Throttling is not available for the Dynamic Router communication point as messages are directly placed on its input queue by an output Dynamic Router communication point. If throttling is desired, then this should instead be configured using output throttling on the output Dynamic Router communication point that sends the message.

Output Mode Properties

The dynamic routing is configured by setting the message property router:Destination to either the full path or target name of the target communication point. It can be set as either a single value or a property list if multiple destinations are desired, and it is valid to use a mixture of full paths and target names. If full paths are used then it is permissible to use either forward or backslashes to separate the path components. If a target name is used then it must be preceded with a single @ character in order to distinguish it from a component path (for example, @myTarget).

A destination must be considered valid in order for it to be used. A valid destination is an instance of the Dynamic Router communication point that is:

• Configured to run in input only mode, and
•  Attached to one or more routes.

Static destinations configured using component paths are validated at configuration time. Only runtime validation is performed on static destinations that use target names.

If multiple destinations are identified for a message due to either multiple paths being provided or a target name being used by multiple input Dynamic Router communication points, all of the evaluated destinations are validated. An error with any of the destinations causes the configured error action to take effect and the message is sent to none of those destinations. This means that duplicate messages are avoided if the user subsequently fixes the message and re-sends it.

If an error occurs evaluating the Static Destination at runtime then the outgoing message is sent to the Error Queue.

Static Destinations

Although the Dynamic Router communication point is designed for dynamically selecting a destination using the router:Destination message property, if need be it can be configured to send messages to a single destination instead. This is done by setting the On Missing Dynamic Destination configuration property to Use Static Destination. The Static Destination configuration property should then be set to the destination to use. As with dynamic destinations, a static destination within a locker can be configured using either the relative component path (for example, myFolder/Dynamic Router 1), or the target name preceded with the @ symbol (for example, @myTarget). A static destination in another locker can be configured using either the full component path preceded by the # symbol (for example, #myLocker/myFolder/Dynamic Router 1), or the target name preceded with the @ symbol.

The  router:Destination message property should not be set when a single static destination is being used.

Multiple Destinations

The Dynamic Router communication point can deliver to multiple destinations in two ways:

• By using a Target Name (for example, @myTarget) which multiple Dynamic Router input communication points have configured as a non-unique target name.
• By dynamically selecting multiple destinations using the router:Destination message property with a property list containing multiple target names or component paths. Property lists are message properties containing multiple values and are set using the addPropertyValue() function in JavaScript. Refer to Message Object for details on how to call this function.

Cross-Locker Destinations

You can use the Dynamic Router communication point to deliver messages across lockers.

Examples

// Create the output message 
var next = output.append(input[0]);

// Set the dynamic router destinations
// Across lockers
next.addPropertyValue("router:Destination", "#Locker 1/Dynamic Router 1");
next.addPropertyValue("router:Destination", "#Locker 2/Folder A/Dynamic Router 2");
next.addPropertyValue("router:Destination", "#Locker 2/Dynamic Router 3");

// Within the same locker
next.addPropertyValue("router:Destination", "Folder A/Dynamic Router 2");

// By targetName
next.addPropertyValue("router:Destination", "@targetName"); 

Usage

There are many potential uses for the Dynamic Router communication point, one of which allows re-usable routes to be built that are connected using instances of the Dynamic Router communication point. This allows multiple other routes in a Rhapsody configuration to use some shared functionality from another route, without the shared route having to be aware of where the messages are coming from.

In the following example, a shared validation route is indirectly connected to another route using the Dynamic Router communication point. The structure of these routes is shown in the following screenshots:

A single output Dynamic Router communication point is shared between the two routes to send messages, and it uses its default configuration.

System 1 Route

Send to Validation Module Filter

The 'Send to Validation Module Filter' is a Property Population filter that is used to initialize the message properties required for routing. The router:Destination message property is used to send the message to the Validation Module, and then the ValidationModuleCaller message property is used by the Validation Module in order to determine where to return the message after finishing with it.

System 1 Router Input Communication Point

The 'System1 Router Input Communication Point' is an input Dynamic Router communication point that receives the message after it has finished processing on the Validation Module. It is configured as follows:

Validation Module Route

Validation Input Communication Point

The 'Validation Input Communication Point' is an input Dynamic Router communication point that receives the message when it is initially sent to the Validation Module. It is configured as follows:

Show Uses

The Show Uses tab in the Information panel in Rhapsody IDE displays the static destination routes or the delivery routes of a Dynamic Router communication point.

Infinite Loop Detection

An infinite loop in Rhapsody occurs when a message continuously flows through one or more routes without ever being able to exit the system. It continues to consume resources until some manual intervention is performed to stop it from processing further. While it is possible to configure an infinite loop using normal cross-route connectors in Rhapsody, such potential loops can generally be seen in the configuration relatively easily. However, the nature of the Dynamic Router communication point (as well as communication points operating in Output mode with continued routing enabled) is such that an infinite loop could be inadvertently configured in a manner that is difficult to detect.

The Dynamic Router communication point provides some built-in protection against inadvertent infinite loops through a configurable limit on the number of times that a single input message can be sent by a Dynamic Router communication point. When this message count threshold is exceeded, the message is immediately sent to the Error Queue when another Dynamic Router communication point attempts to send it. This limit applies to the original input message to Rhapsody, and so is cumulative across all copies of that message if it is split or debatched. In order to limit the datastore space required to keep track of this limit, messages that have not been sent by a Dynamic Router communication point within approximately the last hour have their counts reset to zero. In practice, however, a real infinite loop tends to reach the limit within a matter of seconds.

The default threshold for the infinite loop detection is 50. The threshold can be set by modifying the rhapsody.properties file:

# Maximum number of times that an input message and its descendants can flow through a communication point
#RouterModuleService.maxRouterSendsPerMessage=50

Rhapsody treats any threshold value less than 10 as 10. Changing this setting in the rhapsody.properties file requires a Rhapsody engine restart in order to take effect.

The infinite loop detection threshold can also be changed on a per message basis using a message property. To do so, add a message property to the message called router:MaxRouterSendsPerMessage set to an integer containing the maximum number of times that this message may be sent by a Dynamic Router communication point. Note that when setting this message property, the number of sends is still counted against the original input message, even if multiple splits of that input message have a different configured maximum.

It is also possible to suppress the limit entirely for a message. However, this is only recommended for cases where the threshold has already been reached for a message, and the configuration has subsequently been fixed to remove the infinite loop. The Dynamic Router communication point does not perform any infinite loop detection for a message if the message contains a message property called router:SuppressRouterInfiniteLoopDetection. This property can be manually added to a message while it is on the Error Queue, if required, and then the message can be re-sent out the Dynamic Router communication point in order to allow it to continue processing. The value of this message property is not important: its mere presence causes the infinite loop protection to be disabled.