CBR

CBR (Content Based Routing) is used to route the incoming messages on to different destinations based on the content of the messages. The component creates a port for each of the XPath expressions specified and the messages satisfying the particular XPath is sent to the respective port. In addition to these ports, an output port OUT_FALSE is created and messages whose content does not satisfy any of the XPath expressions will be sent out of this port. If more than one XPath condition is true, the message is sent to all ports for which the XPath condition evaluates to true.

Configuration and Testing

The CBR component can be configured using its Custom Property Sheet wizard.

Schema

The schema of the XML content that is used for routing should be provided using the Schema Editor in the Schema panel.

Refer to the Schema Editor section in Common Components Configurations to know more about the Schema Editor property.

Figure 1: Providing schema

Expand to see the schema used in the figure above.

CODE

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="http://www.fiorano.com/fesb/activity/Text2XML1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://www.fiorano.com/fesb/activity/Text2XML1">
   <xsd:element name="Employee_Schema">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:element minOccurs="0" maxOccurs="unbounded" name="Employee">
               <xsd:complexType>
                  <xsd:sequence>
                     <xsd:element name="EmployeeName" type="xsd:string"/>
                     <xsd:element name="EmployeeID" type="xsd:int"/>
                     <xsd:element name="EmployeeAge" type="xsd:int"/>
                  </xsd:sequence>
               </xsd:complexType>
            </xsd:element>
         </xsd:sequence>
      </xsd:complexType>
   </xsd:element>
</xsd:schema>

After providing the schema, click the Select Root Element ellipsis at the bottom of the panel to select the root element.

The XML content that is used for routing is determined by the Apply Xpath on context property in the Routing Rules panel.

Namespaces

List of namespace prefixes that are used in the XPath and the namespaces that they represent are provided in the Namespaces panel. The table in this panel is automatically populated with namespaces defined in the XML schema provided in the Schema panel.

Figure 2: List of namespaces populated based on the schema provided

To add a new namespace prefix and namespace, enter the details in the empty row and press Enter key.
To remove unnecessary namespaces, select the row containing namespace and click the Delete button.

Routing Rules

XPaths based on which the routing is done can be configured in the Routing rules panel.

The XPath editor can be used to configure XPaths. Click the ellipsis button in the XPath column to open XPath Editor and drag the elements to the editor and then double-click the element to provide rules/conditions. Alternatively, a valid XPath expression can be typed directly in the table.

Figure 3: XPath(s) to be evaluated on the input messages; rules set as EmployeeName='Name1', ExployeeID>200 and EmployeeAge<50

An empty row is automatically added after closing the XPath Editor or after pressing Enter key after the XPath is manually provided.

Refer to XPath Editor section in the Common Configurations page for information about XPath Editor.

For each configured XPath expression, an output port is created with the name provided in the PortName column. Messages satisfying the given XPath condition are routed to this port.

Port names ON_EXCEPTION, OUT_FALSE and ON_TRANSACTION_FAIL are reserved ones for which custom names cannot be set in the PortName column.

XPath in CBR should be configured to return a boolean value for routing messages.
XPath can also contain simply the path of an element, then CBR checks for the existence of the particular element in the input XML. If the input XML contains the element then it will be routed to the corresponding output port of that XPath, if the input XML does not contain the element then it will be routed to the output port OUT_FALSE.
XPath can be valid JMS Message selectors. If the JMS Message selector is used, the runtime argument useFioranoCBR (in Properties panel) should be set to 'true' as shown in Figure 4.

Figure 4: Setting runtime argument 'useFioranoCBR'.

Figure 5: XPath processor properties in the Routing Rules page

Processor

Specifies the processor used to evaluate XPath conditions. If the number of XPath conditions is more (greater than 4), then XSLT processor is preferable for better performance. If the XPath conditions are less then both processors will give equal performance. XPath processor is preferable if the XPaths are complex. XSLT processor might not work for all XPaths.

XPath

Uses Saxon based XPath evaluator to evaluate XPaths. Values in column XPath should be valid XPath expressions. XPaths are validated if XPath processor is selected. The validation will be done for some simple XPath conditions only. So, if the XPath is validated, there is no guarantee that the XPath results a boolean value.

Use XPath 1.0: When this property is selected, XPath 1.0 is used for evaluation. Otherwise, XPath 2.0 is used. This checkbox is visible only when the Processor is selected as XPath.
ApplyXPathonContext: When this property is selected, the XPath is evaluated on the Application Context of the input message. Otherwise, XPath is evaluated on Body of the message.
When XPath is evaluated on Context of the message, no schema is set on the ports of CBR. In case of evaluating text body of the message, schema provided earlier in the configuration (if present) will be set on the ports.

When this option is chosen, provide application context schema in the schema panel.

XSLT

Uses XSLT to evaluate the condition. Values in column XPath can be any valid Boolean condition in XSLT. There is no validation check on XPath conditions if we select XSLT processor.

While using XSLT processor, if XPath contains any functions having namespace prefixes like saxon:parse(), then the appropriate prefix and namespace URL pair should add in the Namespace panel. For example, to use saxon functions namespace, URL http://saxon.sf.net/ should add saxon as a prefix in the Namespace panel.

Example: For a value /ns1:Transaction/ns1:request/ns1:source = 'tserv' provided in column XPath, the following XSL is used:

XML

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ns1="http://www.incomm.com/transaction/2008-02" xmlns:ns2="http://www.w3.org/2001/XMLSchema" version="1.0">
   <xsl:output method="text" encoding="UTF-8" />
   <xsl:template match="/">
      <xsl:if test="/ns1:Transaction/ns1:request/ns1:source ='tserv'">TSERV,</xsl:if>
   </xsl:template>
</xsl:stylesheet>

Functional Demonstration

Scenario

CBR is configured to filter the messages on the basis of employee age in the input message. It is sent to one of the output ports depending on the XPath specified in the CBR.
Configure the CBR as described in Configuration and Testing section and use feeder and display component to send sample input and check the response respectively.

Figure 6: Demonstrating the Scenario with sample input and output

Sample Input

XML

<?xml version="1.0" encoding="UTF-8"?>
<ns1:Employee_Schema xmlns:ns1="http://www.fiorano.com/fesb/activity/XML2Text2">
   <ns1:Employee>
      <ns1:EmployeeName>Name1</ns1:EmployeeName>
      <ns1:EmployeeID>294</ns1:EmployeeID>
      <ns1:EmployeeAge>22</ns1:EmployeeAge>
   </ns1:Employee>
</ns1:Employee_Schema>

Sample Output

With the conditions set as in the Routing Rules section, all the Display microservices display the output below:

XML

<?xml version="1.0" encoding="UTF-8"?>
<ns1:Employee_Schema xmlns:ns1="http://www.fiorano.com/fesb/activity/XML2Text2">
   <ns1:Employee>
      <ns1:EmployeeName>Name1</ns1:EmployeeName>
      <ns1:EmployeeID>294</ns1:EmployeeID>
      <ns1:EmployeeAge>22</ns1:EmployeeAge>
   </ns1:Employee>
</ns1:Employee_Schema>

The Display microservice connected to the OUT_FALSE output port will display empty content for the input specified above.

Use Case Scenario

In Purchasing System sample, a purchase request is sent by the user to a company through a web-based interface. The purchase order consists of three inputs namely REQUEST, CREDENTIALS, and SYNC_PO_002. REQUEST is an identifier string for the request. The request identifier is verified by a CBR (Content Based Router) component to be the correct one for which this system is expected to service the request.

Figure 7: Purchasing System sample

Useful Tips

The order of the XPath conditions specified in the CPS does not matter.
The CBR component supports XPath version 1.0 and 2.0. The default is version 2.0. To use version 1.0, please select the checkbox Use XPath 1.0 in the CPS.
To monitor the time taken for executing each request, set the log level for logger com.fiorano.edbc.cbr.monitor to INFO.
When runtime argument for this component, useFioranoCBR is set to 'true', please make sure that the XPaths provided in the configuration are valid JMS Messages. More information on JMS Message Selectors can be found in the documentation for Message interface in JMS APIs. http://java.sun.com/products/jms/javadoc-102a/index.html.
To apply XPath on context, select ApplyXPathonContext in Routingrules panel and provide Application context schema in the schema panel. In this case, the schema will not be set on output ports.

To understand the service better, refer the Content Based Routing (CBR) example which demonstrates CBR service features.