Skip Headers
Oracle® Web Services Manager Administrator's Guide
10g (10.1.3.3.0)

Part Number E10299-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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:

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:

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:

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

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):

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:

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:

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:

  1. 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.

  2. 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

  1. From the navigation pane of Web Services Manager Control, select Tools, then click Test Page.

  2. 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.

  3. Replace the endpoint URL with the following URL:

    http://host_name:port/gateway/fs/crouter

  4. 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

  1. Start Web Services Manager Control, logged in as Component Administrator for the gateway for which you want to define content routing rules.

  2. 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.

  3. 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 follows
    Description of "Figure 4-1 Edit Component Properties Page"

  4. 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 follows
    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.

  5. 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.

  6. 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).
  7. 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 follows
    Description of "Figure 4-3 Content Routing Page"

  8. 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.

  9. 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 follows
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

  1. Start Web Services Manager Control, logged in as Component Administrator for the gateway for which you want to define content routing rules.

  2. 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.

  3. 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.

  4. Click Content Routing.

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

  5. Click Add, then select the ATTACHMENT XPath option

    The Web Services Manager Control displays the Add/Edit Rule page.

  6. Specify the associated XPath variable, contained in the SOAP message, that identifies attachments to the message. For example:

    /soap:Envelope/soap:Body/source/@href
    
    
  7. 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

  8. 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

  9. Specify the Web service to which to route the message in the THEN field.

  10. 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.