4 Content Routing with Oracle Web Services Manager Gateways

This chapter discusses how to route messages to a gateway based on their content. This chapter includes the following sections:

About Gateway Content Routing Rules
Accessing the Web Service Using Content Routing
Creating Rules for Oracle WSM Content Routing
Creating Rules Using Attachment XPath Content

Using Oracle Web Services Manager (Oracle WSM) Gateway content routing rules, you can customize message routing to send messages to different Web service providers based on the content of the actual messages. The dispatching logic of Oracle WSM Gateway routes incoming messages to different pipelines; and, therefore, different service end points, based on the destination URL in the incoming SOAP message. When the incoming message is not a SOAP message, it is normalized (that is, wrapped) to SOAP, so that the dispatching logic remains the same.

The client needs to know only the client access URL through which it sends its message to the gateway. The gateway then routes the message to the Web service URL. The client does not need to know the URL of the Web service. And, in many cases, you may want to hide this URL from the client for the following reasons:

A gateway may be exposed to business partners, but the Web services are internal and are not published externally.
You may want to designate the service end point based on content and, therefore, you do not want to expose Web service endpoint URLs to the client.

With content routing, a client sends a message to the gateway without any specific forwarding service address. The routing is based on the XML content in the SOAP envelope (header or body) or in a SOAP attachment, and on designated content routing rules. Content routing can be applied to any incoming SOAP message, over any transport protocol, and can be routed to any service registered with the gateway.

When a message arrives at the gateway with a URL prefix that contains /fs, for example, http://host:port/gateway/fs/crouter, the gateway forwards the message to a specific Web service based on the following:

The content of the message
The content routing rules configured at the gateway

This service can be invoked with any of the available transports, for example, HTTP(S), JMS, and MQ, using the following methods:

For HTTP: Send messages to the URL http://host:port/gateway/fs/crouter.
For JMS: Set the services ID in the JMS header or SOAP header to fs:crouter.
For MQ: Set the service ID in the SOAP header to fs:crouter.

About Gateway Content Routing Rules

You configure content-based rules to designate the destination of messages sent to a gateway. The gateway evaluates the message based on these rules.

The following is a simple real-world application use case:

A major insurance company has two Web services that process incoming insurance requests for quotes (RFQs):

Web Service 1 processes RFQs from homeowners.
Web Service 2 processes RFQs from automobile owners.

The insurance company does not want to reveal the URLs for these two services directly to client applications. Instead, it wants to show a single URL to the client, then have the gateway route the message to either Web Service 1 or Web Service 2 based on the clientType field in the RFQ.

A system administrator would create the following rules for the gateway:

Rule 1: IF /soap:Body/RFQ/clientType = HOMEOWNER THEN ROUTE to service1
Rule 2: IF /soap:Body/RFQ/clientType = AUTOOWNER THEN ROUTE to service2

When a message arrives at the gateway, the gateway evaluates each rule, in order, and routes the message according to the first rule that matches.

Content routing rules are based on the creation of XPath1 expressions with simple condition matching. A rule consists of a condition that returns either a true or a false value and an action. More complex conditions for the rule can be created by specifying multiple simple conditions that are connected with the Boolean AND expression:

Table 4-1 Rule Creation Elements

Element	Description
Rule	A rule consists of a condition and an action. A condition is a set of one or more simple conditions that, when evaluated, return either a true or false value. The action specifies a single routing operation that is performed if the associated condition is true.
Condition	A condition consists of one or more simple conditions that are connected using the Boolean AND expression to return either a true or a false value. Simple conditions can be defined using the following operators:EQUALS – Value of an XML element equals X (string match only)NOT_EQUALS – String value on an XML element does not match XEXISTS – XML element exists in SOAP header or body or attachmentNOT_EXISTS – XML element does not exist in SOAP header or body or attachment
Action	If the associated condition is true, the action routes or forwards the message to the specified Web service.

Using Web Services Manager Control, you can do the following:

Add a new content routing rule by specifying a new condition (variable-XPath, conditional operator, value) or specifying the name space prefix, if necessary, for defining the variable-XPath.
List and view all the content routing rules.
Delete a content routing rule.
Change the priority order in which content routing rules are evaluated.
Specify the address for target Web services.

Content routing rules use the following syntax:

Conditions: IF <variable> <EQUALS/EXISTS> <value>

Namespaces: WHERE <prefix> = <namespace_url>

Action: THEN Route To <serviceId>

Namespaces

Application namespaces vary from application to application and are entirely dependent on the design guidelines of the application.

SOAP-ENV is a namespace that points to http://schemas.xmlsoap.org/soap/envelope/

Sample SOAP Message

The following code sample show a typical SOAP message:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <r:RFQ xmlns:r="http://businessdocs.com/RFQ">
         <clientType>HOMEOWNER</clientType>
         <clientID>12345</clientID>
      </r:RFQ>
   </soap:Body>
</soap:Envelope>

Sample Content Routing Rules

The following provides a description of two sample content routing rules that could be defined for the previous sample SOAP message:

If /soap:Envelope/soap:Body/r:RFQ/clientType equals HOMEOWNER where the SOAP namespace is http://schemas.xmlsoap.org/soap/envelope/ and the r namespace is http://businessdocs.com/RFQ, then route to Service1.
If /soap:Envelope/soap:Body/r:RFQ/clientType equals AUTOOWNER where the SOAP namespace is http://schemas.xmlsoap.org/soap/envelope/ and the r namespace is http://businessdocs.com/RFQ, then route to Service2.

Accessing the Web Service Using Content Routing

This section describes how to access a Web service using content routing.

To access the Web service using content routing

From the navigation pane of Web Services Manager Control, select Tools, then click Test Page.
Enter the URL for a Web service that is registered to the gateway, and click Submit Query.

The Test Web Service page refreshes and displays the endpoint URL as well as other parameters that you can set.
Replace the endpoint URL with the following URL:

http://host_name:port/gateway/fs/crouter
Click Invoke.

Creating Rules for Oracle WSM Content Routing

The procedure that follows creates content routing rules for the sample SOAP message:

If /soap:Envelope/soap:Body/r:RFQ/clientType equals HOMEOWNER where the SOAP namespace is http://schemas.xmlsoap.org/soap/envelope/ and the r namespace is http://businessdocs.com/RFQ, then route to Service1.

To create rules for Oracle WSM content routing

Start Web Services Manager Control, logged in as Component Administrator for the gateway for which you want to define content routing rules.
In the navigation pane, select Policy Management, then select Manage Policies.

The Web Services Manager Control displays a list of currently registered Oracle WSM components, including gateways.
Click Edit for the gateway for which you want to add content routing.

Web Services Manager Control displays the Edit Component Properties page, showing a list of the properties currently assigned for the gateway component.

Figure 4-1 Edit Component Properties Page

Description of "Figure 4-1 Edit Component Properties Page"
Click Content Routing.

Web Services Manager Control displays a list of currently defined content routing rules for the gateway, if any are defined.

Figure 4-2 Content Routing Details Page

Description of "Figure 4-2 Content Routing Details Page"

Oracle WSM provides a default content routing rule based on the condition No match, which is invoked if no other content routing condition matches.
Click Add.

Web Services Manager Control displays an empty Add/Edit Rule page where you specify the conditions and actions for a new content routing rule. By default, the SOAP Envelope option is selected.
Enter the IF condition in the SOAP message in the IF field, and enter the Web service to which to route the message in the THEN field.

Note:
To route the message to a specific service location, you can specify its service name (specified during service registration) or the service ID number (SID).
Click WHERE and specify the namespaces for any XPath variables included in the IF conditions of the rule (Figure 4-3).

In the insurance example, the first content routing rule is: If /soap:Envelope/soap:Body/r:RFQ/clientType equals HOMEOWNER where the SOAP namespace is http://schemas.xmlsoap.org/soap/envelope and the r namespace is http://businessdocs.com/RFQ then route to Service1.

Figure 4-3 Content Routing Page

Description of "Figure 4-3 Content Routing Page"
When you have finished your entries, click Save.

Web Services Manager Control displays the content routing rules, including any new rules you added.

The order in which rules are listed reflects the order in which content routing rules are applied to a message sent to the gateway. Since the incoming message is routed according to the first rule that Oracle WSM Gateway verifies as true, you may want to change the order of the listed rules to match whatever selection criteria is best suited for your environment.
Click on the up or down arrow to change the order of the rules.

When you click Namespace, a window opens that displays all XML namespaces used across all the rules defined for this gateway.

Figure 4-4 Namespace Mappings for Content Routing Rules

Description of "Figure 4-4 Namespace Mappings for Content Routing Rules"

A prefix can be mapped to only one namespace across all content routing rules for the gateway. In Figure 4-4, there are two prefixes, r and soap. You cannot, for example, have the same prefix, both named soap, mapped to different namespaces.

Creating Rules Using Attachment XPath Content

In addition to defining content routing rules based on the XML content of SOAP messages, you can also define rules that are based on the XPath content of SOAP attachments.

To create rules using attachment XPath content

Start Web Services Manager Control, logged in as Component Administrator for the gateway for which you want to define content routing rules.
In the navigation pane, click Policy Management, then click Manage Policies.

Web Services Manager Control displays a list of currently registered Oracle WSM components, including gateways.
Click Edit for the gateway for which you want to add content routing.

Web Services Manager Control displays the Edit Component Properties page, showing a list of the properties currently assigned for the gateway component.
Click Content Routing.

Web Services Manager Control displays a list of currently defined content routing rules for the gateway, if any are defined.
Click Add, then select the ATTACHMENT XPath option

The Web Services Manager Control displays the Add/Edit Rule page.
Specify the associated XPath variable, contained in the SOAP message, that identifies attachments to the message. For example:
```
/soap:Envelope/soap:Body/source/@href
```
Enter one or more rule conditions to match the attachment content. In the IF field, specify XPath variables found in the attachment. For example:

IF /policy/model EQUALS lexus
Click WHERE and specify the namespaces for any XPath variables included in the IF conditions of the rule. For example:

http://schemas.xmlsoap.org/envelope
Specify the Web service to which to route the message in the THEN field.
Click Save.

The new attachment XPath rule now shows up in the display of defined gateway content routing rules.

Note:
Attachment XPath content routing rules can be defined only for attachments with XML content. These attachments must be referenced inside the SOAP message using the SOAP-with-Attachments specification.