WSO2 ESB - Rule Mediator

Rule Mediator

Rule mediator has been implemented based on Java Rule Engine API JSR-94. This provides the capability required for mediation using rules. Rules enable to cope with the uncertainty of the business logic. Rule Mediator extends the mediation in the way , mediation logic can be defined in terms of rules.

Syntax

  <rule  xmlns="http://ws.apache.org/ns/synapse">
      <configuration xmlns="http://www.wso2.org/products/wso2commons/rule">
          <ruleSource [key="String"] [sourceFormat="String(xml|native)"]>
          In-lined
          </ruleSource>

          <provider uri="rule service provider uri" class="rule service provider implementation">
              <property name="String" value="String"/>*
          </provider>

          <ruleSet>
              <creation>
                  <property name="String" value="String"/>*
              </creation>
              <registration>
                  <property name="String" value="String"/>*
              </registration>
              <deregistration>
                  <property name="String" value="String"/>*
              </deregistration>
          </ruleSet>

          <ruleSession  [type="stateful|stateless"]>
              <property name="String" value="String"/>*
          </ruleSession>

          <input name="String" type="String"  [expression="XPath"] [value="String"] [key="String"] [class="String"]>
              <property name="String" type="String"  [expression="XPath"] [value="String"] [key="String"] />*
          </input>*

          <output name="String" type="String"  [expression="XPath"] [value="String"] [key="String"] [class="String"]>
              <property name="String" type="String"  [expression="XPath"] [value="String"] [key="String"] />*
          </output>*
      </configuration>

      <childMediators>
          any mediators
      </childMediators>
  </rule>        

RuleSource

Note : The key or in-lined rule script must be defined. Otherwise, rule mediator is invalid.

RuleSession

Provider

RuleSet

Inside ''ruleSet' , it is possible to exists properties for ruleset creation,registration,deregistration .

Ex: When using Drool native language(.drl) for rule script , it would be need to provide .dsl file .This is done using two property .One is with name 'source' and vakue 'drl'. Other is with name 'dslKey' and with the value (a registry key to look up dsl file. )

      <ruleSet>
         <creation>
             <property name="source" value="drl"/>
             <property name="dslKey" value="registry_key"/>
         </creation>
      </ruleSet>

Input / Output

For type custom , It is need to provides the class name from attribute class

For custom type it is possible to serialize it as a XML and attached it to the SOAP message. There is a sample to illustrate this capability. Please refers the sample guide.

A Custom Java Object ("input" / "output" with type "custom") can be configured using 'property' inside 'input / output' definitions. There is a sample to illustrate this capability. Please refers the sample guide.

For input , the values are calculated based on value or combination of key and expression. The expression of the 'input' defines source node to get data. These values are bind into the rule engine from its 'name' so that those can be accessed with in rule engine by name.

All the inputs are wrapped with org.wso2.rule.Inputs so that any value can be accessed as inputs.get(name). Please refers to samples.

Output describes what should do with return value form rule engine. To set any return value , there is an abstraction org.wso2.rule.Outputs

outputs.put(key,value)

These return values can be set back to the SOAP envelope or message context. The 'output' defines the how should set a return value. The expression of the 'output defines target node. The name of the 'output' and the key (outputs.put(key,value)) should be matched in order to set the value back , otherwise return value will be skipped. There is a spacial value called "execute_children" in 'output' and this indicates whether it is need to execute children mediators inside rule mediator. The children mediators are defined inside tag 'childMediators' .

Ex: outputs.put("execute_children","true"); will execute child mediators.

UI Configuration

Rule

Figure1: Rule Mediator

Each of configuration elements is described in following section

RuleSource

Rule script can be given as a registry key or an in-lined script. To give rule script as in-lined, you can use editor.

Source Format - XML or native

The format (language) of the rule script . If it is a XML, then this attribute should be 'xml'. Any other value, rule mediator assumes that the rule script is in native format. If the rule script is in native format, it should be given by wrapping as a CDATA section inside a XML tag ex: <X><![CDATA[ native code]]></X>.

Note: The key or in-lined rule script must be defined. Otherwise, rule mediator is invalid.

RuleServicePprovider

Class - Rule service provider class (The rule service provider implementation). The default value is Drools implementation.

URI- Rule service provider Uri. The default value is Drools implementation.

property - Those are used when creating the rule service provider.

RuleSession

Session Type - Indicates the stateful or stateless behavior of the rule engine. If this has value ' stateful ' , then rule engine will executes rules in a state full manner , for any other value , it assumes as stateless.

property - Those are used when creating rule session.

RuleSet

It is possible to exists properties for rules set creation, registration, deregistration and there are add property options for each.

Example Usage: When using Drool native language (.drl) for rule script, it is needed to provide .dsl file .This can be done using attribute named 'source' and value 'drl'.

<ruleSet>

<creation>

<property name="source" value="drl"/>

</creation>

</ruleSet>

Input / Output

Input defines what are the facts that should injected to Rule Engine in order to fire rules whereas Output describes what should do with return value form rule engine.

Adding Input / Output

Figure 2 shows a one senario of addting input

Rule Mediator Inputs width="1319" height="122">

Figure 2 Inputs of the Rule Mediator

Type : According to current implementation valid types are as bellow.

Name : Value Type Static Value or XPath expression

Value / Expression :value - Represents any static value. expression- XPath expression is used to extract data from either external XML source or SOAP envelope. There is no default value.

Registry Key : The registry or Message context key .This is used for getting data from either registry or message context

Registry Browser : If the key is registry resource, the browser to select the resource.

NS Editor : You can click this link to add namespaces if you are providing an expression. You will be provided another panel named 'Namespace Editor' where you can provide any number of namespace prefixes and url

Action : Delete the input out put

Adding Properties

Adding properties option is in RuleServiceProvider , RuleSet and RuleSession. Figure 3 shows UI on adding property.

Property Adding

Figure3: Rule Mediator Properties

Name: Name for the property

Value: The type of the property value.

Action: Delete the property

Example

  1. <rule>
          <configuration xmlns="http://www.wso2.org/products/wso2commons/rule">
             <ruleSource key="rule/sample.xml"/>
             <input name="symbol" expression="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples" type="string"/>
          </configuration>
          <childMediators>
              <send>
                   <endpoint>
                       <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                   </endpoint>
              </send>
              <drop/>
           </childMediators>
    </rule>
        
    In the above configuration, Rule script is picked from the registry with key rule/sample.xml. There is a one input and it is a string variable. Its value is calculated from the current SOAP message using an expression. These inputs are data to the Rule engine. Rule engine uses inputs to decide what rules should fire.