20 Creating Mediator Routing Rules

20.2.2.1 Specifying Mediator Services or Events

After creating the Mediator, you associate it to inbound service operations or event subscriptions and specify the targets of the Mediator. Targets are outbound service operations or event publishing. A target specifies the next service or event to which a Mediator should send the message and what service operation is to be invoked. You can specify a service or an event as target type.

You can also echo source messages back to the initial caller after any transformations, validations, assignments, or sequencing are performed. Whether the echo is synchronous or asynchronous, depends on the WSDL file of the caller. The echo option is only available for inbound service operations and is not available for event subscriptions.

The purpose of the echo option is to expose all the Mediator functionality as a callable service, without having to route to any other service. For example, you can call a Mediator to perform a transformation, a validation, or an assignment, and then echo the Mediator back to your application, without routing anywhere else.

You can specify multiple routings for an inbound operation or event. Each routing is mapped to one target service invocation or event. Therefore, to specify multiple service invocations or raise multiple events, you must specify one routing rule for each target. For example, a message payload, you want to invoke an operation from the following operations defined in a service:

• insert

• update

• updateid

• delete

You must create four routings, one for each operation. Later, when you specify a filter expression, you can specify which target and operation is applied to each message instance, because of the message payload as shown in Figure 20-3.

Figure 20-3 Multiple Routings for an Inbound Operation

Description of "Figure 20-3 Multiple Routings for an Inbound Operation"

To invoke a service:

1. In the Routing Rules panel, click Add.

   The Target Type dialog is displayed as shown in Figure 20-4.

   Figure 20-4 Target Type Dialog

   
   Description of "Figure 20-4 Target Type Dialog"
   
   

2. Click Service.

3. In the Target Services dialog, navigate to, and then select an operation provided by a service, as shown in Figure 20-5.

   Figure 20-5 Target Services Dialog

   
   Description of "Figure 20-5 Target Services Dialog"
   
   

   Note:

   A service can consist of multiple operations as shown in Figure 20-5.

4. Click OK.

To raise an event:

1. In the Routing Rules panel, click Add.

   The Target Type dialog is displayed as shown in Figure 20-6.

2. Click Event.

   The Event Chooser dialog is displayed.

3. Click Search to the right of Event Definition field.

   The SCA Resource Browser dialog is displayed.

4. Select an event file and click OK.

   The Event field is populated with the events defined in the selected file as shown in Figure 20-6.

   Figure 20-6 Event Chooser Dialog

   
   Description of "Figure 20-6 Event Chooser Dialog"
   
   

5. Select an event.

6. Click OK.

To echo a service:

1. In the Routing Rules panel, click Add.

   The Target Type dialog is displayed as shown in the following figure:

   Figure 20-7 Target Type Dialog

   
   Description of "Figure 20-7 Target Type Dialog"
   
   

2. Click Echo.

   The following figure shows a routing rule with a synchronous echo:

   Note:

   An asynchronous echo has an icon with a dotted line on the return.

   Figure 20-8 Sample Mediator Supporting Echo Operation

   
   Description of "Figure 20-8 Sample Mediator Supporting Echo Operation"
   
   

Restrictions on Using Echo Option

The echo option has the following limitations:

• The echo option is supported only with the Mediator interfaces having the following types of WSDL files:

  • Request/Reply

  • Request/Reply/Fault

  • Request/Callback

  Note:

  The echo option is not available for Mediator interfaces having Request/Reply/Fault/Callback WSDL Files.

• The echo option is available for synchronous operations like Request/Reply and Request/Reply/Fault.

  Note:

  The echo option is available for the synchronous operations only when the routing rule is sequential because parallel routing rules are not supported for Mediators with synchronous operations.

• For synchronous operations, having a conditional filter set, the echo option does not return any response to the caller, when the filter condition is set to false. Instead, a null response is returned to the caller.

• The echo option is available for asynchronous operations only if the Mediator interface has a callback operation. In this case, the echo is run on a separate thread.

  Note:

  The asynchronous echo option is available only when the routing rule is parallel. To use the echo option, then sequential routing rules are not supported for Mediators with asynchronous operations.

20.2.2.2 Specifying Sequential or Parallel Execution

You can specify execution type for a routing rule. A routing rule execution type can be parallel or sequential. To specify an execution type for a routing rule, select Sequential or Parallel execution type from the Routing Rules panel.

This section describes the following sections:

• Basic Principles of Sequential Routing Rules

• Basic Principles of Parallel Routing Rules

Basic Principles of Sequential Routing Rules

• In sequential execution, routings are evaluated and actions are performed sequentially. Sequential routings are evaluated in the same thread and transaction as the caller.

• Mediator always enlists itself into the global transaction propagated through the thread that is processing the incoming message. For example, if an inbound JCA adapter invokes a Mediator, then the Mediator enlists itself to the transaction that the JCA adapter has initiated.

• Mediator propagates the transaction through the same thread as the target components, while executing the sequential routing rules.

• Mediator never commits or rolls back transactions propagated by external entities.

• Mediator manages the transaction only if the thread-invoking Mediator does not have an active transaction already. For example, if Mediator is invoked from inbound SOAP services, then Mediator starts a transaction, and commits or rolls back the transaction depending on success and failure.

Basic Principles of Parallel Routing Rules

• In parallel execution, routings are queued and evaluated in parallel in different threads.

  For parallel processing, the messages of each Mediator component are retrieved in weighted round robin fashion. This ensures that all Mediator components receive parallel processing cycles, even if one or more Mediator components produce higher number of messages compared to other components. The weight used is the message priority set during design time of a Mediator component. Higher number of parallel processing cycles are allocated to the components that have higher message priority.

  You can use the Priority user interface Construct to set the priority of a Mediator component. You can a set a priority from zero to nine, nine being the highest priority. The default priority is four.

  Note:

  The Priority user interface Construct is applicable only to parallel routing rules.

• A new transaction is initiated by the Mediator for processing each parallel rule. The initiated transaction ends with an enqueue to the Mediator parallel message dehydration store.

  For example, if a Mediator component has one parallel routing rule, then one message is enqueued on the Mediator parallel message dehydration store. Then, the parallel message dispatcher to the store initiates a transaction, reads the message from the Database store and invokes the target component or service of this routing rule. This transaction initiated by the listener thread is a completely new transaction and is propagated to the target components.

  Note:

  Dehydrating of messages means storing the incoming messages in database for parallel routing rules, so that they can be processed later by worker threads.

• In parallel execution, Mediator commits or rolls back transactions because it is the initiator of these transactions.

If an operation or event has both sequential and parallel routing rules, first sequential routing rules are evaluated and actions are performed, and then parallel routings are queued for parallel execution.

20.2.2.3 Handling Response Messages

You can specify how to handle the response messages in synchronous and asynchronous interactions. In case of synchronous interactions, you can specify the transformations and assignments for the response and the fault message. You can forward the response and the fault message to another service or event. Otherwise, you can send them back to the initial caller, if the initial caller is expecting responses and faults.

In case of asynchronous interaction, you can specify a timeout period for receiving the response. The timeout period can be specified in seconds, hours, days, months, or years. By default, the timeout period is infinite. If a callback response does not come within the specified timeout period, then a timeout response can be forwarded to another service, event, or back to the initial caller.

You cannot route a Mediator response to a two-way service. If you want to route a response to a two-way service, then you should use a one-way Mediator in between the first Mediator and the two-way service. The response should first be forwarded to the one-way Mediator, which in turn should call the two-way service.

Specifying a Timeout Period

Perform the following steps to specify a timeout period:

1. Click the Browse for target service operation icon next to the <<Target Operation>> field in the Callback section.

   The Target Type dialog is displayed.

2. Select Service or Event.

   The Target Service or the Event Chooser dialog is displayed depending upon the selection you made.

3. Select an event or service.

4. Click OK.

   The timeout response is forwarded to the specified service or event.

20.2.2.4 Handling Multiple Callbacks

A single Mediator cannot handle multiple callbacks. If you have a composite application with a Mediator that receives multiple callbacks, then the behavior of the composite application is undetermined. For example, consider the scenario shown in Figure 20-9, where, AsyncMediator forwards the callback response from AsyncEchoMediator1 and AsyncEchoMediator2 to FileInMediator. In such a flow, the AsyncMediator may return the callback from both the AsyncEchoMediator1 and AsyncEchoMediator2, or from either one of them. The exact behavior is stochastic and cannot be predicted.

Figure 20-9 Sample Mediator Handling Multiple Callback

Description of "Figure 20-9 Sample Mediator Handling Multiple Callback"

20.2.2.5 Handling Faults

If you create a new routing rule, where the target service WSDL operation has one or more faults, then you still see a single Fault routing section in the Mediator Editor window. If the source Mediator service supports one or more faults, then the fault is routed back to the caller by default. You can choose the source and target fault names to be routed. You may also use the service browser to route the fault to another target.

To route another fault, click Add another fault routing button shown in the following figure:

Figure 20-10 Adding a Second fault

Description of "Figure 20-10 Adding a Second fault"

This adds another fault section to the routing rule. In the following figure, a second fault is being routed to a File adapter service:

Figure 20-11 Adding a Second Fault

Description of "Figure 20-11 Adding a Second Fault"

While choosing the target for a fault routing, if you want to remove a fault routing section, then you must click Delete the selected fault routing as shown in Figure 20-12.

Figure 20-12 Deleting a Fault Routing

Description of "Figure 20-12 Deleting a Fault Routing"

Otherwise, you can also click Clear Target on the Target Type dialog as shown in the following figure:

Figure 20-13 Target Type Dialog

Description of "Figure 20-13 Target Type Dialog"

20.2.2.6 Specifying Expression for Filtering Messages

The filter expression routing rule enables you to filter messages based on their payload. If the filter expression for a given message instance evaluates to true, then the message is delivered to the target service or event specified within the routing rule.

For example, suppose you want to route your data to customers in two different countries: US and Canada. However, you only want notices regarding the product line of type MOBILE to be sent to the customers in US and the product line of type LANDLINE to the customers in Canada. To implement this routing, you must define a routing rule for each component/operation pair that sends messages to the target customers. In addition, you specify filter expressions for the routing rules that send messages to the customers in US or Canada.

You can also define filter expressions message properties or message headers.

Filter Expression Message Properties

Following two are examples of filter expressions message properties:

$in.property.custom.Priority = '1'

$in.property.tracking.ecid = '2'

Filter Expression Message Headers

Following two are examples of filter expressions message headers:

$in.header.wsse_Security/wsse:Security/Priority = '234'

$in.header.wsse_Security/wsse:Security/Priority = '234'

For the preceding filter expressions message headers to work, you must add the following attribute to the root element of the .mplan file:

wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

You can specify a filter expression by using the Expression Builder dialog as shown in Figure 20-14. The Expression Builder dialog is displayed when you click the icon to the right of the filter expression field in the Routing Rules panel.

Figure 20-14 Expression Builder Dialog

Description of "Figure 20-14 Expression Builder Dialog"

The Expression Builder dialog contains the components and controls that assist you in designing a filter expression. Briefly, you double-click a value in the Variables field or the Functions palette, to add the value to the Expression field. Using a combination of Variable elements, functions, and manually entered text, you can build an expression by which you want message payloads to be filtered for a given routing rule.

The following list describes each of the fields in the Expression Builder dialog:

• Expression field

  You can enter the filter expression – either manually, or by using the Variable field and the Functions palette in this field.

  The icons on the upper right side of this field enable you to undo the last edit made, redo the last edit made, or clear the entire Expression field, respectively.

• Variables field

  This field contains the message defined for a Mediator. Oracle JDeveloper parses the Mediator WSDL file and presents the message definition in the Variables field. The input message is stored in the $in variable. You can use $in.properties to access properties of an input message.

  If the input message consists of multiple parts, then you can use $in.<partname> to access a part of an input message as shown in Figure 20-15.

  Figure 20-15 Multiple Part Message in Expression Builder

  
  Description of "Figure 20-15 Multiple Part Message in Expression Builder"
  
  

• Functions Palette

  This list enables you to select different functions to include in an expression. When you select a function, a preview of how that function appears when added to the Expression field is presented in the Content Preview field, and a description of the function is presented in the Description field.

• Content Preview

  This field indicates how a value selected from the Variables field or Functions palette appears when it is inserted into the Expression field.

• Description

  This field describes the value selected from the Variables field or Functions palette.

To specify a filter expression on a message payload, follow these steps:

1. In the Routing Rules panel, click the Add Filter Expression icon, shown in Figure 20-2.

   The Expression Builder dialog is displayed.

2. In the Variables field, expand the message definition and select the message element on which you want to base the expression. For example, CustomerID element is shown selected in Figure 20-16.

   Figure 20-16 Expression Builder Dialog – Variables Element Selected

   
   Description of "Figure 20-16 Expression Builder Dialog – Variables Element Selected"
   
   

3. Click Insert Into Expression.

   The expression is added in the Expression field, as shown in Figure 20-17.

   Figure 20-17 Expression Builder Dialog – Variables Element Inserted

   
   Description of "Figure 20-17 Expression Builder Dialog – Variables Element Inserted"
   
   

4. From the Function list, select the function to apply to the message payload. For example, equals.

   Functions are grouped in categories that are listed when you click the down arrow in the Functions list. For example, if you click the down arrow and select Logical Functions, the list appears as shown in Figure 20-17. When you select a function within the Logical Functions list, a description of that function is presented in the Description box.

5. Click Insert Into Expression.

   The XPath expression for the selected function is inserted in to the Expression field.

6. Complete the expression. In this example, a value of 1001 is entered, as shown in Figure 20-18.

   Figure 20-18 Sample Expression Builder Dialog – Value Entered

   
   Description of "Figure 20-18 Sample Expression Builder Dialog – Value Entered"
   
   

7. You can edit the expression manually, or use the expression editing icons, which are summarized in Figure 20-19.

   Figure 20-19 Expression Editing Icons

   
   Description of "Figure 20-19 Expression Editing Icons"
   
   

8. Click OK.

   The expression is added to the Routing Rule panel.

To modify or delete a filter expression, double-click the Add Filter Expression icon, and then modify or delete the expression in the Expression field of the Expression Builder.

20.2.2.7 Creating Transformations

Oracle JDeveloper provides an XSLT Data Mapper tool that enables you to specify a mapper file (XSL file) to transform data from one XML schema (expressed as an XSD file) to another. This tool enables data interchange among applications using different schemas. For example, you can map incoming source purchase order schema to an outgoing invoice schema. After you define an XSL file, you can reuse it in multiple routing rule specifications.

When you click the transformation map icon to the right of the Transform Using field in the Routing Rules panel, the Request Transformation Map dialog is displayed. You can select an existing XSL file or create a new XSL file with the Data Mapper tool to perform the required transformation.

You can also specify transformations for a synchronous reply, callback response message, or a fault message. In case of synchronous reply or fault message, the Reply Transformation Map dialog or the Fault Transformation Map dialog contains the Include Request in the Reply Payload option. Figure 20-21 shows a Reply Transformation Map dialog with this option.

Figure 20-21 Reply Transformation Map Dialog

Description of "Figure 20-21 Reply Transformation Map Dialog"

When you select this option, an $initial variable is created which contains the original message of a synchronous interaction as shown in Figure 20-22.

Figure 20-22 Initial Variable in XSL File

Description of "Figure 20-22 Initial Variable in XSL File"

An initial message can also consist of multiple parts. You can use $initial.<partname> to access a part of the initial message.

For information about the Data Mapper tool, see Chapter 35, "Creating Transformations with the XSLT Mapper".

20.2.2.8 Assigning Values

You can use the Assign Values field to specify the properties of a target message. Figure 20-23 shows the Assign Values dialog that is displayed when you click the Assign Values icon in the routing rules panel.

Figure 20-23 Assign Values Dialog

Description of "Figure 20-23 Assign Values Dialog"

To set the properties of the target message:

1. Click Add in the Assign Values dialog.

   The Assign Value dialog is displayed as shown in Figure 20-24.

   Figure 20-24 Assign Value Dialog

   
   Description of "Figure 20-24 Assign Value Dialog"
   
   

2. In the From section, select any of the following options from Type box:

   • Property: Select this option to assign value of a property to the target message. The property list contains a list of predefined message properties. You can also enter any user-defined property name.

   • Expression: Select this option to assign value of an expression to the target message. When you click the Invoke Expression Builder icon to the right of Expression field, the Expression Builder dialog similar to the one shown in Figure 20-14 is displayed.

     For more information about the Expression Builder dialog, see Section 20.2.2.6, "Specifying Expression for Filtering Messages".

   • Constant: Select this option to assign a constant value to the target message.

3. In the To section, select any of the following options:

   • Property: Select this option to copy the value to a message property. The Variable field of the Expression Builder dialog contains an $out variable that contains the output message. You can use $out.properties to access properties of an output message.

   • Expression: Select this option to copy the value to an expression. When you click the Invoke Expression Builder icon to the right of Expression field, the Expression Builder dialog is displayed. The Variable field of the Expression Builder dialog contains an $out variable that contains the output message. You can use $out.<partname> to access a complete output message or part of an output message. Note that you cannot assign any value after the <partname>. For example, in Figure 20-25, the expression is $out.request and you cannot modify it to add any value after request.

   Figure 20-25 shows a sample Assign Value dialog in which a constant value is specified as an expression.

   Figure 20-25 Populated Assign Value Dialog

   
   Description of "Figure 20-25 Populated Assign Value Dialog"
   
   

4. Click OK in the Assign Value dialog.

5. Click OK. The expression is added to Assign Values field of the Routing Rules panel.

20.2.2.9 Access Headers for Filters and Assignments

When the Expression Builder is invoked from a Mediator, either for defining a filter or for defining an assignment source or target, the WSDL file is parsed. This automatically detects any SOAP headers for the current routing rule operation and makes them visible as Variables under the in or out folder as header./ns_elementName/, as shown in Figure 20-26. Here, ns is the namespace prefix and elementName is the root element name for the header schema.

For example:

Example 1

Suppose, the namespace prefixes wsse and ns1 are already defined in the WSDL file or the .mplan file, then you can write an XPath expression as the following:

$in.header.wsse_Security/wsse:Security/ns1:Foo/Priority

Example 2

Suppose, you want to use a schema that does not have a namespace predefined in the WSDL file, then the Expression Builder is enhanced to allow you to enter {full_namespace} instead of a prefix. The Expression Builder then generates a unique prefix and the prefix definition is added to the .mplan file.

For example, enter the following expression in the Expression Builder:

$in.header.{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd}_Security/
{"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xs
d"}:
Security/{"http://www.globalcompany.com/ns/OrderBooking"}:Foo/Priority

The .mplan file contains the following:

xmlns:ns1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

xmlns:ns2="http://www.globalcompany.com/ns/OrderBooking"

...

expression="$in.header.ns1_Security/ns1:Security/ns2:Foo/Priority"

Figure 20-26 Expression Builder Dialog - Automatic Header Detection

Description of "Figure 20-26 Expression Builder Dialog - Automatic Header Detection"

By default, SOAP headers are not passed through by Mediator. You must add the following endpoint property to the corresponding Mediator routing service:

<property name="passThroughHeader">true</property> 

For example, to add this property, you can modify the Composite.xml file in the following way:

<component name="Mediator1"> 
     <implementation.mediator src="Mediator1.mplan"/>
     <property name="passThroughHeader">true</property>
</component>

$in.header.<header root element namespace prefix>_<header root element name>/<xpath>

<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sec
ext-1.0.xsd">
<Priority>234</Priority>
</wsse:Security>

$in.header.wsse_Security/wsse:Security/Priority = '234'

<copy target="$out.property.jca.jms.priority"
 expression="$in.header.wsse_Security/wsse:Security/Priority"/>

wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

$in.property.tracking.ecid = '2'

<copy target="$out.property.tracking.ecid"  value="$in.property.tracking.ecid"/>

20.2.2.10 Using Semantic Validation

You can specify Schematron files for validating an inbound message and its various parts. Schematron version 1.5 is the supported version.

Perform the following steps for specifying a Schematron schema to validate an inbound message and its various parts:

1. Click the Select Validation File icon to the right of Validate Semantic field.

   The Validations dialog is displayed.

2. Click Add.

   The Add Validation dialog is displayed.

3. From the Part list, select a message part.

4. Click Search to the right of the File field.

   The SCA Resource Browser dialog is displayed.

5. Select a Schematron file and click OK.

   Note:

   • Schematron files usually have a .sch extension.

   • No error message or warning is displayed if the selected Schematron file is empty.

   The Add Validation dialog is updated, as shown in Figure 20-27.

   Figure 20-27 Add Validation Dialog

   
   Description of "Figure 20-27 Add Validation Dialog"
   
   

6. Click OK.

   The Validation dialog is updated, as shown in Figure 20-28.

   Figure 20-28 Validation Dialog

   
   Description of "Figure 20-28 Validation Dialog"
   
   

7. Click Add to specify a Schematron file for another message part or click OK.

   For more information about building a Schematron schema, refer to the resources available at

   http://www.schematron.com

   Note:

   In semantic validation, if you check for the length of each element name, then the element name may change for different set of input. This happens when there are white spaces between nodes because the parser treats the white spaces as test nodes.

20.2.2.11 Support for Java Callouts

Java callouts enable you to use external Java classes to manipulate messages flowing through the Mediator. Only one Java callout is supported per WSDL operation or event subscription. The callout class must implement the oracle.tip.mediator.common.api.IjavaCallout interface. Callouts are available for both static and dynamic routings. Figure 20-29 shows a sample Mediator with two operations, where both the operations have one routing rule each and the first operation has a callout class.

Figure 20-29 Sample Mediator Supporting Java Callout

Description of "Figure 20-29 Sample Mediator Supporting Java Callout"

You must ensure that the Java callout class is available on the server. You can use any of the following methods for this:

• Copy the Java class to the SCA-INF/classes folder

• Copy the JAR containing the Java class to the SCA-INF/lib folder

• Copy the JAR containing the Java class to the $DOMAIN_HOME/lib folder

If you want to make the Java callout class to be available to multiple Mediators, then you must copy the JAR containing the Java class to the $DOMAIN_HOME/lib folder.

You can manually enter the name of the Java callout class in the Callout To field as shown in Figure 20-30. In this case, JDeveloper's auto-completion information feature completes the address, the classes in the current project.

Figure 20-30 Callout To Field

Description of "Figure 20-30 Callout To Field"

You can also click Select java callout class button to invoke the standard JDeveloper Class Browser as shown in Figure 20-31.

Figure 20-31 JDeveloper Class Browser

Description of "Figure 20-31 JDeveloper Class Browser"

The Class Browser is filtered so that it only displays classes that implement the oracle.tip.mediator.common.api.IjavaCallout interface.

If you have a Java callout in Mediator and use a filter expression in the same Mediator, then you must set the root element for the payload as follows:

changexmldoc = XmlUtils.getXmlDocument(ChangedDoc);
String mykey = "request";
message.addPayload(mykey,changexmldoc.getDocumentElement());

Table 20-1 discusses the methods in the oracle.tip.mediator.common.api.IjavaCallout interface.

<assign>
<copy target="$out.property.jca.file.FileName" expression="$in.property.jca.file.FileName"/>
</assign>

Table 20-2 discusses the methods in the CalloutMediatorMessage interface.

20.2.3 Creating Dynamic Routing Rules

The basic idea behind dynamic routing is to separate the control logic, which determines the path taken by the process, from the execution of the process. In the dynamic routing scenario, a decision matrix is used to determine the type of Level-2 service to be chosen for each routing. The factors that affect the decision on the type of Level-2 service are channel, customer type, and so on. The solution allows this decision matrix to be modified externally by business analysts without changing the routing. The decision matrix must be evaluated to determine the outbound service.

Dynamic routing rules can be created by using the Dynamic Routing Rule option of Mediator Editor window, as shown in Figure 20-32:

Figure 20-32 Mediator Editor Window Displaying Dynamic Routing Rule Option

Description of "Figure 20-32 Mediator Editor Window Displaying Dynamic Routing Rule Option"

This creates a new Business Rules component and the Business Rule component is wired to the Mediator component within the SCA composite of the Mediator component. The wire links between the Business Rule component and the Mediator component are considered implementation details and are shown as dotted lines in the SCA editor, as shown in Figure 20-33:

Figure 20-33 SCA Editor with Wire Links Between the Business Rule Component and the Mediator Component

Description of "Figure 20-33 SCA Editor with Wire Links Between the Business Rule Component and the Mediator Component"

The Business Rule component comprises of a rule dictionary. The rule dictionary is a metadata container for the rule engine artifacts, such as fact types, rulesets, rules, decision tables and so on. As part of creating the Business Rules component, the rule dictionary is pre-initialized with the following data:

• Fact Type Model

  The fact type model is the data model that can be used for modeling rules. The rule dictionary is populated with a fact type model that corresponds to the input of the phase activity, and some fixed data model that is required as part of the contract between the Mediator component and the Business Rules component.

• Ruleset

  A ruleset is a container of rules and used as a kind of grouping mechanism for rules. A ruleset can be exposed as a service. As part of creating the Business Rules component, one ruleset is created within the rule dictionary.

• Decision Table (or Matrix)

  From a rule engine perspective, a decision table is a collection of rules with the same fact type model elements in the condition and action part of the rules. The decision table enables to visualize rules in a tabular format. As part of creating the Business Rules component, a new decision table is created within the ruleset.

• Decision Service

  As part of creating the Business Rules component, a decision service is created to expose the ruleset as a service of the Business Rules SCA component. The service interface is used by the Mediator component to evaluate the decision table.

After all the required artifacts of the phase activity are created, the wizard starts modeling the phase decision matrix (PDM). The wizard launches the Rule Designer window of JDeveloper and enables you to edit the phase decision matrix. Figure 20-34 shows a sample decision table within the Rule Designer:

Figure 20-34 Sample Decision Table Within the Rule Designer

Description of "Figure 20-34 Sample Decision Table Within the Rule Designer"

Once the dynamic routing is created, you can modify the associated decision matrix by clicking Edit Dynamic Rules. This launches the Rule Designer and enables modification of the associated decision table of the Business Rules component. After you create dynamic routing for the Mediator component, you cannot go back to static routing without deleting the dynamic routing. Currently, there is no option for mixing these two types of routing.

The Mediator mplan file looks like the following after dynamic routing option is chosen:

Figure 20-35 Mediator mplan File for a Mediator with Dynamic Routing Rule

Description of "Figure 20-35 Mediator mplan File for a Mediator with Dynamic Routing Rule"

You see the following changes in the source view:

<Mediator name="Shipment" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns="http://xmlns.oracle.com/sca/1.0/mediator">
 <operation name="execute" deliveryPolicy="AllOrNothing" priority="0">
  <switch decisionServiceRef="Phase1DecisionService"
          decisionServiceOperation="executeFunction"></switch>
 </operation>
</Mediator>

The switch element contains the decision service reference and operation details to enable the Mediator component to invoke the decision service in runtime for getting the dynamic routing decisions. Dynamic decisions are returned by rule engine user configuration in Runtime.

External service invocation contains an extra attribute called bindingInfo, which contains binding information to make the invocation dynamic.

Limitations on Mediators Using Dynamic Routing Rules

Following are some limitations on Mediators using dynamic routing rules:

• As of now, only SOAP bindings are supported. There is a dummy SOAP binding in the composite.xml file. This endpoint is overridden by Mediator in runtime through NM property. So, outbound services can be called only over SOAP.

• Payload manipulation is limited for dynamic routing rules. No assignment, transformation, or validation can be performed.

• The reference WSDL file (Layer 2 or Called References) should have the same abstract WSDL file as the Phase Reference that gets auto created.

• Dynamic Routing is not possible for Mediators with synchronous or one-way interface.

20.3 Creating a Mediator for Routing Messages

The CustomerRouter use case provides an overview of how to use a Mediator in a SOA composite sample application to route messages the payload. For downloading the sample files mentioned in this section, visit the following URL:

http://www.oracle.com/technology/sample_code/products/mediator

The CustomerRouter use case consists of the following steps:

1. Legacy customer files are picked up from a directory by an adapter service named ReadCust.

2. The ReadCust adapter service sends the file data to the CustomerRouter Mediator.

3. The CustomerRouter Mediator applies a filter to the XML message payload to determine whether the message should be routed to the USCustomer reference or CanadaCustomer reference.

4. The CustomerRouter Mediator then transforms the message to the structure required by the adapter reference.

5. The external reference delivers the message to its associated external application.

Figure 20-36 provides an overview of the CustomerRouter use case.

Figure 20-36 Overview of CustomerRouter Use Case

Description of "Figure 20-36 Overview of CustomerRouter Use Case"

20.3.1 Step-By-Step Instructions for Creating the CustomerRouter Use Case

This section provides the design-time tasks for creating, building, and deploying the use case. These tasks should be performed in the order in which they are presented.

• Section 20.3.1.1, "Task 1: Creating an Oracle JDeveloper Application and Project"

• Section 20.3.1.2, "Creating CustomerRouter Mediator Component"

• Section 20.3.1.3, "Creating a File Adapter Service"

• Section 20.3.1.4, "Creating a File adapter reference"

• Section 20.3.1.5, "Specifying Routing Rules"

• Section 20.3.1.6, "Creating Oracle Application Server Connection"

• Section 20.3.1.7, "Deploying CustomerRouterProject"

20.3.1.1 Task 1: Creating an Oracle JDeveloper Application and Project

To create an application and a project for the use case:

1. In Oracle JDeveloper, click File and select New.

   The New Gallery dialog appears.

2. In the New Gallery, expand the General node, and select the Applications category.

3. In the Items list, select SOA Application and click OK.

   The Create SOA Application Wizard appears.

4. In the Application Name field, enter CustomerRouter and then click Next.

   The Name your project screen appears.

5. In the Project Name field, enter CustomerRouterProject and click Next.

   The Configure SOA settings screen appears.

6. In the Composite Template list, select Empty Composite and then click Finish.

   The Applications Navigator of Oracle JDeveloper is populated with the new application and the project, and the Design tab contains a blank palette.

7. From the File menu, click Save All.

20.3.1.2 Creating CustomerRouter Mediator Component

To create a Mediator named CustomerRouter:

1. From the Component Palette, select SOA.

2. Drag and drop a Mediator to the Components design area.

   The Create Mediator dialog is displayed.

3. Enter CustomerRouter in the Name field.

4. Select Define Interface Later from Templates.

5. Click OK.

   A Mediator with name CustomerRouter is created.

20.3.1.3 Creating a File Adapter Service

You must create a File adapter service named ReadCust to read the XML files from a directory.

Note:

Mediator may process the same file twice when run against Oracle RAC planned outages. This is because a File adapter is a non-XA compliant adapter. So, when it participates in a global transaction, it may not follow the XA interface specification of processing each file only once.

To create a File adapter service:

1. From the Components Palette, select SOA.

2. Select File Adapter and drag it to the Exposed Services design area.

   The Adapter Configuration Wizard Welcome page is displayed.

3. Click Next.

   The Service Name page is displayed.

4. In the Service Name field, enter ReadCust.

5. Click Next.

   The Adapter Interface page is displayed.

6. Select Define from operation and schema (specified later) and click Next.

   The Operation page is displayed.

7. In the Operation Type field, select Read File.

8. In the Operation Name field, replace Read with ReadFile.

9. Click Next.

   The File Directories page is displayed.

10. In the Directory for Incoming Files (physical path) field, enter the directory from which you want to read the files. For example, C:\Customer\In.

11. Click Next.

    The File Filtering page is displayed.

12. In the Include Files with Name Pattern field, enter *.xml, and then click Next.

    The File Polling page is displayed.

13. Change the Polling Frequency field value to 10 seconds, and then click Next.

    The Messages page is displayed.

14. Click Search to the right of the URL field.

    The Type Chooser dialog is displayed.

15. Click Import Schema File.

    The Import Schema File dialog is displayed.

16. Click Search to the right of the URL field and select the LegacyCustomer.xsd file present in the Samples folder.

17. Click OK.

18. Expand the navigation tree to Type Explorer\Imported Schemas\LegacyCustomer.xsd and select CustomerData, as shown in Figure 20-37.

    Figure 20-37 Type Chooser - CustomerData

    
    Description of "Figure 20-37 Type Chooser - CustomerData"
    
    

19. Click OK.

    The Adapter Configuration wizard appears as shown in Figure 20-38.

    Figure 20-38 Adapter Configuration Wizard – Messages page

    
    Description of "Figure 20-38 Adapter Configuration Wizard – Messages page"
    
    

20. Click Next.

    The Finish page is displayed.

21. Click Finish.

22. From the File menu, click Save All.

20.3.1.4 Creating a File adapter reference

You must create a File adapter reference USCustomer.

To create a File adapter reference:

1. From the Component Palette, select SOA.

2. Select File Adapter and drag it to the External References design area.

   The Adapter Configuration Wizard Welcome page is displayed.

3. Click Next.

   The Service Name page is displayed.

4. In the Service Name field, enter USCustomer.

5. Click Next.

   The Adapter Interface page is displayed.

6. Select Define from operation and schema (specified later) and click Next.

   The Operation page is displayed.

7. Click Next.

   The Operation page is displayed.

8. In the Operation Type field, select Write File.

9. In the Operation Name field, enter WriteFile.

10. Click Next.

    The File Configuration page is displayed.

11. In the Directory for Outgoing Files (physical path) field, enter the name of the directory where you want to write the files.

    For example, C:\Customer\out.

12. In the File Naming Convention field, enter customer_%SEQ%.xml and click Next.

    The Messages page is displayed.

13. Click Search to the right of the URL field.

    The Type Chooser dialog is displayed.

14. Click Import Schema File.

    The Import Schema File dialog is displayed.

15. Click Search to the right of the URL field and select the USCustomer.xsd file present in the Samples folder.

16. Click OK.

17. Expand the navigation tree to Type Explorer\Imported Schemas\USCustomer.xsd and then select Customer.

18. Click OK.

19. Click Next.

    The Finish page is displayed.

20. Click Finish.

21. From the File menu, click Save All.

Create another File adapter reference CanadaCustomer in similar way by using the CanCustomer.xsd file.

Figure 20-39 shows how the SOA composite editor appears after performing this task.

Figure 20-39 Mediator Component with Adapter Services and References

Description of "Figure 20-39 Mediator Component with Adapter Services and References"

20.3.1.5 Specifying Routing Rules

You must specify the path that messages take from the ReadCust adapter service to external references.

To specify routing rules:

1. Connect the ReadCust service to the CustomerRouter Mediator as shown in Figure 20-40.

   This specifies the File adapter service to invoke the CustomerRouter Mediator while reading a file from the input directory.

   Figure 20-40 Connecting ReadCust Service to the CustomerRouter Mediator

   
   Description of "Figure 20-40 Connecting ReadCust Service to the CustomerRouter Mediator"
   
   

2. Double-click CustomerRouter Mediator to open the CustomerRouter.mplan editor shown in Figure 20-41.

   Figure 20-41 CustomerRouter Mediator in Mediator Editor

   
   Description of "Figure 20-41 CustomerRouter Mediator in Mediator Editor"
   
   

3. In the Routing Rules section, click Add to the extreme right side of ReadFile and then click static routing rule.

   The Target Type dialog is displayed.

4. Click Service.

   The Target Services dialog is displayed.

5. Navigate to CustomerRouterProject, References, USCustomer and select WriteFile as shown in Figure 20-42.

   Figure 20-42 Target Services Dialog

   
   Description of "Figure 20-42 Target Services Dialog"
   
   

6. Click OK.

   The Routing Rules panel is displayed, as shown in Figure 20-43.

   Figure 20-43 The Routing Rules Panel - MapCustomerData Added

   
   Description of "Figure 20-43 The Routing Rules Panel - MapCustomerData Added"
   
   

7. Click the filter icon next to the <<Filter Expression>> field to create a filter expression for this routing rule.

   The Expression Builder dialog is displayed.

8. In the Variables field, navigate to Variables, in, body, imp1:CustomerData, and then select Country.

9. Double-click Country.

   The Country node is added in the Expression field as shown in Figure 20-44.

   Figure 20-44 Expression Builder Dialog

   
   Description of "Figure 20-44 Expression Builder Dialog"
   
   

10. Modify the expression to the following:

    $in.CustomerData/imp1:CustomerData/Country='US'
    

11. Click OK.

    The <<Filter Expression>> field of the Routing Rules panel is populated with the expression as shown in Figure 20-45.

    Figure 20-45 Populated Filter Field of Routing Rules Panel

    
    Description of "Figure 20-45 Populated Filter Field of Routing Rules Panel"
    
    

12. Click the icon to the right of the Transform Using field.

    The Request Transformation Map dialog is displayed, as shown in Figure 20-46.

    Figure 20-46 Request Transformation Map

    
    Description of "Figure 20-46 Request Transformation Map"
    
    

13. Select Create New Mapper File and click OK.

    A CustomerData_To_Customer.xsl tab is added, as shown in Figure 20-47.

    Figure 20-47 CustomerData_To_Customer.xsl Tab – Initially

    
    Description of "Figure 20-47 CustomerData_To_Customer.xsl Tab – Initially"
    
    

14. Drag and drop the imp1:CustomerData source element to imp1:Customer target element.

    The Auto Map Preferences dialog is displayed.

15. From the During Auto Map options, deselect Match Elements Considering their Ancestor Names.

    The Auto Map Preferences dialog is shown in Figure 20-48.

    Figure 20-48 Auto Map Preferences Dialog

    
    Description of "Figure 20-48 Auto Map Preferences Dialog"
    
    

16. Click OK.

    The CustomerData_To_Customer.xsl tab appears as shown in Figure 20-49.

    Figure 20-49 CustomerData_To_Customer.xsl Tab – Auto Mapped Connections

    
    Description of "Figure 20-49 CustomerData_To_Customer.xsl Tab – Auto Mapped Connections"
    
    

17. From the File menu, click Save All.

18. Repeat the steps mentioned in Step 3 through 17 to specify CanadaCustomer reference as the target service. In the Expression builder dialog, specify the following expression:

    Note:

    For repeating the steps, you must reenter the Mediator Editor by closing the Mapper Editor or by clicking the CustomerRouter.mplan tab.

    $in.CustomerData/imp1:CustomerData/Country='CA'
    

    Figure 20-50 shows how the Mediator editor would appear after you have specified CanadaCustomer reference as target service.

    Figure 20-50 Routing Rules Panel with Target Services Defined

    
    Description of "Figure 20-50 Routing Rules Panel with Target Services Defined"
    
    

    After performing all the steps mentioned in this section, the SOA composite editor would appear as shown in Figure 20-36.

20.3.1.6 Creating Oracle Application Server Connection

An Oracle Application Server connection is required for deploying your SOA composite application. For information on creating Oracle Application Server connection, refer to Oracle Fusion Middleware User's Guide for Technology Adapters.

20.3.1.7 Deploying CustomerRouterProject

Deploying the CustomerRouterProject composite application to Oracle Application Server consists of following steps:

• Creating an Application Deployment Profile

• Deploying the Application Deployment Profile to Oracle Application Server

For detailed information about these steps, see Section 38.7.1, "Deploying a Single SOA Composite in Oracle JDeveloper".

http://hostname:portnumber/em

20.4 Creating Asynchronous Request Response Using Mediator

This sample demonstrates asynchronous request response scenario using Mediator. This composite has a client BPEL process invoking a Mediator, which invokes a server BPEL process. All the invocations are done as asynchronous request response.

Figure 20-51 provides an overview of the AsyncMediator use case.

Figure 20-51 Overview of AsyncMediator Use Case

Description of "Figure 20-51 Overview of AsyncMediator Use Case"

For downloading the sample files mentioned in this section, visit the following URL:

http://www.oracle.com/technology/sample_code/products/mediator