About the Message Routing sample

The Message Routing sample shows how you can use a database table or file to store information that a message flow can use to route messages to WebSphere MQ queues. This approach is an alternative to creating hard-coded routing information in a message flow Compute node.

Using a database table or file are ways of storing any form of routing or transformation data in WebSphere Message Broker. They offer the following advantages:

One problem with using databases or files to store this information is the performance cost that is incurred when accessing the database or file each time a message passes through a message flow.

To solve this problem, shared variables can be used. With shared variables you can store state in message flows that is available to all messages that are using the flow. The exact details of how shared variables are used can be found in DECLARE statement in the WebSphere Message Broker documentation. By using shared variables, information from database tables or files can be stored in-memory in a message flow. This approach removes the requirement for continued access to the database table or file, and gives almost all of the advantages of using a database table or file without the performance cost. However, the cache does not pick up changes to the database table or file as they happen. To pick the changes up, you must either restart the message flow or add a refresh mechanism to the message flow.

The Message Routing sample shows how you can use a database table or file to route messages in a message flow, and how a message flow can use shared variables to store the database table or file. It also shows how you can refresh the cached database table by restarting the message flow or by sending a refresh message to the message flow.

Message routing by using a database

Routing_using_database_table message flow

This simple message flow reads a message from a WebSphere MQ queue, creates a destination list based on data in a database table and then routes the message to the entries in the destination list.

Routing_using_database_table message flow

Routing_using_database_and_memory_cache message flow

A sample showing how to route a message by using a cached version of the database table stored in shared variables. The message flow has two main subflows. The first subflow gives the same functions as the Routing_using_database_table message flow but by using shared variables. The second subflow is used to refresh the shared memory variables.

Routing_using_database_and_memory_cache message flow

Message routing by using a file

Three scenarios show how to route messages using the FileRead node. The first uses a file in XML format, and the second and third in comma-separated value (CSV) format. The formats shown are examples. You can use any file format, whether you are reading in the whole file or selecting a single record from the file.

Routing_using_whole_file message flow

This message flow reads a message from a WebSphere MQ queue. The whole file is then read in, and a destination list is created, based on the contents of the file. In this scenario the file is in XML format. The messages are routed to the entries in the destination list.

Routing_using_whole_file message flow

Routing_using_records_file flow

The FileRead node in this sample uses an XPath expression to locate the correct record in the file, based on a key in the incoming message. The file used in this scenario contains records in a CSV format. A message set is used to model each record in the file. The routing information from the record is copied directly to the destination data list, to be used directly by the MQOutput node. As a result, no additional processing (for example by a Compute node) is needed.

Routing_using_records_file flow

Routing_using_file_and_memory_cache message flow

This flow extends the previous flow, by showing how to use ESQL shared variables to cache information from the file. An additional subflow refreshes the shared variable cache.

Routing_using_file_and_memory_cache message flow

Three XPath expressions can be set on the result tab of the FileRead node:

Property Expression Explanation
Result Data Location $ResultRoot/MRM/data From the record that is selected, this field in the record is used to enrich the message. The contents of this field are copied to the output data location.
Output Data Location $OutputLocalEnvironment/Destination/MQ
Record selection expression (concat(
$InputRoot/XMLNSC/SaleEnvelope/SaleList/Invoice/Initial[1],
$InputRoot/XMLNSC/SaleEnvelope/SaleList/Invoice/Initial[2]
) = $ResultRoot/MRM/Initial )
AND
($InputRoot/XMLNSC/SaleEnvelope/SaleList/Invoice/Surname = $ResultRoot/MRM/Surname)
The first part of the expression concatenates the two initials in the message. The second part of the expression takes the surname part of the message. The record that matches the initials and surname is propagated.

Test message

The test message that is used to drive the Message Routing sample is an XML message that contains invoice details for a customer.

<SaleEnvelope>
  <Header>
    <SaleListCount>1</SaleListCount>
  </Header>
  <SaleList>
    <Invoice>
      <Initial>T</Initial>
      <Initial>D</Initial>
      <Surname>Montana</Surname>
      <Item><Code>00</Code>
        <Code>01</Code><Code>02</Code>
        <Description>Twister</Description>
        <Category>Games</Category>
        <Price>00.30</Price>
        <Quantity>01</Quantity>
      </Item>
      <Item>
        <Code>02</Code><Code>03</Code><Code>01</Code>
        <Description>The Times Newspaper</Description>
        <Category>Books and Media</Category>
        <Price>00.20</Price>
        <Quantity>01</Quantity>
      </Item>
      <Balance>00.50</Balance>
      <Currency>Sterling</Currency>
    </Invoice>
  </SaleList>
  <Trailer>
    <CompletionTime>12.00.00</CompletionTime>
  </Trailer>
</SaleEnvelope>

The Initial and Surname fields are used to perform the lookup to find the destination queue for each customer.

Database table used for routing the invoice XML message

The sample message flows use the same database table from which to get the routing information. The database table contains five columns: the first three contain look-up information that is derived from the incoming message and the last two columns contain the details of the queue and queue manager to which the message is routed. The columns are shown in the following table:

Column Description
Variable1 The first variable that is used in looking up the destination queue (This variable is hard-coded in the sample and is not derived from the XML message).
Variable2 The second variable that is used in looking up the destination queue (This variable is derived from the XML message by using the Initial field).
Variable3 The third variable used in looking up the destination queue (This variable is derived from the XML message by using the Surname field).
Queue_manager The destination queue manager name.
Queue_name The destination queue name.

The definition for the database table is provided in the sample message flow project in the Database directory. The database table is not directly linked to the incoming XML message so that it is possible to reuse this table for different routing messages. If the database table was directly linked to the incoming XML message, the first variable might be used to differentiate between different nodes that are using the same table.

Each of the message flows Compute nodes contains detailed ESQL comments explaining exactly what has been done to achieve the required behavior:

How you view the contents of the database for the sample depends on which database product is installed. For DB2 databases use the tools provided by DB2; for example, the DB2 Control Center.

File used for routing the invoice XML message

Routing_using_whole_file message flow

Two XML files are used in this message flow. They both have the same structure, but one contains multiple destinations for the message. The XML file has two elements:

Routing_using_records_file message flow and Routing_using_file_and_memory_cache message flow

These message flows use a CSV file. The file contains multiple records, each of which have four elements:

Each of the Compute nodes of the message flows contain detailed ESQL comments explaining exactly what has been done to achieve the required behavior:

Message set used for routing using records from a file

The image below shows the message set used for the message flows Routing_using_records_file and Routing_using_file_memory_cache.

Message Set

From the message set you can see each of the fields shown in the CSV file. The DestinationData element repeats once for every destination queue that the message will be sent to.

Back to sample home