Author: supun Date: Fri Jun 26 01:59:41 2009 New Revision: 40036 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=40036
Log: Adding rule mediator guide Added: branches/esb/java/2.1/product/docs/xdoc/mediators/rule.xml Added: branches/esb/java/2.1/product/docs/xdoc/mediators/rule.xml URL: http://wso2.org/svn/browse/wso2/branches/esb/java/2.1/product/docs/xdoc/mediators/rule.xml?pathrev=40036 ============================================================================== --- (empty file) +++ branches/esb/java/2.1/product/docs/xdoc/mediators/rule.xml Fri Jun 26 01:59:41 2009 @@ -0,0 +1,318 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml";> +<head> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> + <title>WSO2 ESB - Rule Mediator </title> + <link href="css/esb-docs.css" rel="stylesheet" /> + <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" + media="all" /> +</head> + +<body> +<h2>Rule Mediator</h2> + +<p>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. </p> + +<h3>Syntax</h3> +<pre xml:space="preserve"> <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> </pre> + +<h4 id="RuleSource">RuleSource</h4> +<ul> + <li>key- The registry key which is used to get the rule script from the + registry . </li> + <li>sourceFormat- 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 wrapping as a CDATA section inside a XML + tag ex: <X><![CDATA[ native code]]></X> </li> +</ul> + +<p>Note : The key or in-lined rule script must be defined. Otherwise, rule +mediator is invalid. </p> + +<h4 id="RuleSessio">RuleSession</h4> +<ul> + <li>session- Indicates the state full or state less behavior of the rule + engine. If this has value 'stateful' , then rule engine will executes rules + in a state full manar , for any other value , it assumes as stateless. </li> + <li><property>* - Zero or more properties (Synapse Mediator Property) + can be defnied. Those are used when creating rule session. </li> +</ul> + +<h4 id="Provider">Provider </h4> +<ul> + <li>class- Rule service provider class (The rule service provider + implementation ) The default value is Drools implementation. </li> + <li>uri- Rule service provider Uri.The default value is Drools + implementation. </li> + <li><property>* - Zero or more properties (Synapse Mediator Property) + can be defnied. Those are used when creating the rule service provider. + </li> +</ul> + +<h4>RuleSet</h4> + +<h3 id="RuleSet"></h3> + +<p>Inside ''ruleSet' , it is possible to exists properties for ruleset +creation,registration,deregistration . </p> + +<p>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. ) </p> +<pre> <ruleSet> + <creation> + <property name="source" value="drl"/> + <property name="dslKey" value="registry_key"/> + </creation> + </ruleSet></pre> + +<h4 id="Input">Input / Output</h4> +<ul> + <li>name - The unique name</li> + <li>key- The registry or Message context key .This is used for getting data + from either registry or message context </li> + <li>value- Represents any static value</li> + <li>expression- XPath expression is used to extract data from either external + XML source or SOAP envelope. There is no default value. </li> + <li>type- Defines the type of the data in input. + <p>According to this implementation valid types are as bellow.</p> + <ul> + <li>int</li> + <li>integer</li> + <li>byte</li> + <li>short</li> + <li>double</li> + <li>float</li> + <li>boolean</li> + <li>long</li> + <li>string</li> + <li>omelement - OMElement</li> + <li>sequence - sequence (Synapse sequence )</li> + <li>custom - Any Java Object</li> + </ul> + </li> +</ul> + +<p>For type <strong>custom </strong>, It is need to provides the class name +from attribute <strong>class </strong> </p> + +<p>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. </p> + +<p>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. </p> + +<p>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. </p> + +<p>All the inputs are wrapped with <strong>org.wso2.rule.Inputs</strong> so +that any value can be accessed as <strong>inputs.get(name)</strong>. Please +refers to samples. </p> + +<p>Output describes what should do with return value form rule engine. To set +any return value , there is an abstraction +<strong>org.wso2.rule.Outputs</strong> </p> + +<p><strong>outputs.put(key,value)</strong> </p> + +<p>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 +<strong>"execute_children</strong>" in 'output' and this indicates whether it +is need to execute children mediators inside rule mediator. The children +mediators are defined inside tag 'childMediators' . </p> + +<p>Ex: <strong>outputs.put("execute_children","true")</strong>; will execute +child mediators. </p> + +<h3>UI Configuration</h3> + +<p><img src="../rule-mediator/docs/images/rule_mediator_1.JPG" alt="Rule" /> +</p> + +<p><strong>Figure1: Rule Mediator</strong> </p> + +<p></p> + +<p>Each of configuration elements is described in following section</p> + +<p></p> + +<h4>RuleSource</h4> + +<p>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. </p> + +<p>Source Format - XML or native</p> + +<p>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>. </p> + +<p>Note: The key or in-lined rule script must be defined. Otherwise, rule +mediator is invalid. </p> + +<h4>RuleServicePprovider</h4> + +<p>Class - Rule service provider class (The rule service provider +implementation). The default value is Drools implementation. </p> + +<p>URI- Rule service provider Uri. The default value is Drools implementation. +</p> + +<p>property - Those are used when creating the rule service provider.</p> + +<h4>RuleSession</h4> + +<p>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. </p> + +<p>property - Those are used when creating rule session.</p> + +<h4>RuleSet</h4> + +<p>It is possible to exists properties for rules set creation, registration, +deregistration and there are add property options for each. </p> + +<p>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'. </p> + +<p><ruleSet></p> + +<p><creation></p> + +<p><property name="source" value="drl"/></p> + +<p></creation></p> + +<p></ruleSet></p> + +<h4>Input / Output</h4> + +<p>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. </p> + +<h4>Adding Input / Output</h4> + +<p>Figure 2 shows a one senario of addting input</p> + +<p><img alt="Rule Mediator Inputs" +src="../rule-mediator/docs/images/rule_mediator_input.JPG" /> width="1319" +height="122"> </p> + +<p>Figure 2 Inputs of the Rule Mediator </p> + +<p></p> + +<p><strong>Type :</strong> According to current implementation valid types are +as bellow. </p> +<ul> + <li>int</li> + <li>integer</li> + <li>byte</li> + <li>short</li> + <li>double</li> + <li>float</li> + <li>boolean</li> + <li>long</li> + <li>string</li> + <li>omelement - OMElement</li> + <li>sequence - sequence (Synapse sequence )</li> + <li>custom - Any Java Object</li> +</ul> + +<p><strong>Name :</strong> Value Type Static Value or XPath expression </p> + +<p><strong>Value / Expression :</strong> <em>value</em> - Represents any static +value. <em>expression</em>- XPath expression is used to extract data from +either external XML source or SOAP envelope. There is no default value. </p> + +<p><strong>Registry Key : </strong>The registry or Message context key .This is +used for getting data from either registry or message context </p> + +<p><strong>Registry Browser :</strong> If the key is registry resource, the +browser to select the resource. </p> + +<p><strong>NS Editor</strong> : 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 </p> + +<p><strong>Action</strong> : Delete the input out put </p> + +<h4>Adding Properties</h4> + +<p>Adding properties option is in RuleServiceProvider , RuleSet and +RuleSession. Figure 3 shows UI on adding property. </p> + +<p><img alt="Property Adding" +src="../rule-mediator/docs/images/rule_mediator_property.JPG" /> width="717" +height="64"> </p> + +<p>Figure3: Rule Mediator Properties</p> + +<p><strong>Name</strong>: Name for the property </p> + +<p><strong>Value</strong>: The type of the property value. </p> + +<p><strong>Action</strong>: Delete the property </p> + +<p></p> +</body> +</html> _______________________________________________ Esb-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/esb-java-dev
