Menu
▾
▴
[Jboss-svn-commits] JBL Code SVN: r4945 - in labs/jbossrules/trunk/documentation/manual/en: . Chapter-JSR94 Chapter-Rule_Engine
|
From: <jbo...@li...> - 2006-07-07 17:41:46
|
Author: mar...@jb... Date: 2006-07-07 13:41:07 -0400 (Fri, 07 Jul 2006) New Revision: 4945 Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-How_To_Use.xml labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Introduction.xml labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-References.xml labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Specification.xml labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml labs/jbossrules/trunk/documentation/manual/en/master.xml Log: JBRULES-364 documentation improvements Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-How_To_Use.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-How_To_Use.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-How_To_Use.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -2,96 +2,193 @@ <section> <title>How To Use</title> - <para>This section explains not yet in detail the use of the Java Rule - Engine API with the implementation for JBoss Rules.</para> + <para>There are two parts to working with JSR94. The first part is the + administrative api that deals with building and register RuleExecutionSets, + the second part is runtime session execution of those + RuleExecutionSets.</para> <section> - <title>J2SE Environment</title> + <title>Building and Registering RuleExecutionSets</title> - <para>This section shows you, how to use JBoss Rules over the Java Rule - Engine API in your java applications.</para> - </section> + <para>The RuleServiceProviderManager manages the registration and + retrieval of RuleServiceProviders. The Drools RuleServiceProvider + implementation is automatically registered via a static block when the + class is loaded using Class.forName; in much the same way as JDBC + drivers.</para> - <section> - <title>J2EE Environment</title> + <para><example> + <title>Automatic RuleServiceProvider Registration</title> - <para>If you are using JBoss Rules in a container managed environment, you - might want to use it as a service. This section presents, how to use the - rule engine with the JNDI (Java Naming and Directory Interface) or using - it inside of an enterprise application such as web archive (WAR), java - archive (JAR) or enterprise archive (EAR), which is deployed into the - server.</para> - </section> + <programlisting>// RuleServiceProviderImpl is registered to "http://drools.org/" via a static initialization block +Class.forName("org.jcp.jsr94.jess.RuleServiceProviderImpl"); - <section> - <title>Domain Specific Languages (DSL)</title> +// Get the rule service provider from the provider manager. +RuleServiceProvider ruleServiceProvider = RuleServiceProviderManager.getRuleServiceProvider("http://drools.org/");</programlisting> + </example>The RuleServiceProvider provides access to the RuleRuntime and + RuleAdministration APIs. The RuleAdministration provides an administration + API for the management of RuleExecutionSets, making it possible to + register a RuleExecutionSet that can then be retrieved via the + RuleRuntime. </para> - <para>It is possible to use Domain Specific Languages together with the - Java Rule Engine API. The DSL is shipped to the Rule Engine with the Map - of properties, when you are creating a RuleExecutionSet. Just insert the - content of your dsl file as a String with the key "dsl" into the Map. The - excerpt shows how it works:</para> + <para>First you need to create a RuleExecutionSet before it can be + registered; RuleAdministration provides factory methods to return an empty + LocalRuleExecutionSetProvider or RuleExecutionSetProvider. The + LocalRuleExecutionSetProvider should be used to load a RuleExecutionSets + from local sources that are not serializable, like Streams. The + RuleExecutionSetProvider can be used to load RuleExecutionSets from + serializable sources, like DOM Elements or Packages. Both the + "ruleAdministrator.getLocalRuleExecutionSetProvider( null );" and the + "ruleAdministrator.getRuleExecutionSetProvider( null );" take null as a + parameter, as the properties map for these methods is not currently used. + </para> - <programlisting>Reader reader = new FileReader( "jsr94.dsl" ); -StringBuffer text = new StringBuffer(); -char[] buf = new char[1024]; int len = 0; -//Writes the file content in the StringBuffer -while ( ( len = reader.read( buf ) ) >= 0 ) -{ - text.append( buf, 0, len ); -} -HashMap properties = new java.util.HashMap( ); -properties.put( "name" , "JSR94_Example" ); -properties.put( "description", "no description" ); -//Put the dsl as a String, use the key "dsl" -properties.put( "dsl", text.toString( ) ); -reader = new FileReader( "jsr94.drl" ); -RuleServiceProviderManager.registerRuleServiceProvider( "http://drools.org", Class.forName( "org.drools.jsr94.rules.RuleServiceProviderImpl" ) ); -RuleServiceProvider ruleServiceProvider = RuleServiceProviderManager.getRuleServiceProvider( "http://drools.org" ); -RuleExecutionSet ruleExecutionSet = ruleSetProvider.createRuleExecutionSet( reader, properties ); -RuleAdministrator ruleAdministrator = ruleServiceProvider.getRuleAdministrator( ); -ruleAdministrator.registerRuleExecutionSet( "JSR94_Example", ruleExecutionSet, properties );</programlisting> + <example> + <title>Registering a LocalRuleExecutionSet with the RuleAdministration + API</title> - <para>Do not forget to declare the expander -in this case "jsr94.dsl"- in - your rule file (drl).</para> + <programlisting>// Get the RuleAdministration +RuleAdministration ruleAdministrator = ruleServiceProvider.getRuleAdministrator(); +LocalRuleExecutionSetProvider ruleExecutionSetProvider = ruleAdministrator.getLocalRuleExecutionSetProvider( null ); + +// Create a Reader for the drl +URL drlUrl = new URL("http://mydomain.org/sources/myrules.drl"); +Reader drlReader = new InputStreamReader( drlUrl.openStream() ); + +// Create the RuleExecutionSet for the drl +RuleExecutionSet ruleExecutionSet = ruleExecutionSetProvider.createRuleExecutionSet( drlReader, null ); +</programlisting> + </example> + + <para>"ruleExecutionSetProvider.createRuleExecutionSet( reader, null )" in + the above example takes a null parameter for the propties map; however it + can actually be used to provide configuration for the incoming source. + When null is passed the default is used to load the input as a drl. + Allowed keys for a map are "source" and "dsl". "source" takes "drl" or + "xml" as its value; set "source" to "drl" to load a drl or to "xml" to + load an xml source; xml will ignore any "dsl" key/value settings. The + "dsl" key can take a Reader or a String (the contents of the dsl) as a + value.</para> + + <example> + <title>Specifying a DSL when registering a LocalRuleExecutionSet</title> + + <programlisting>// Get the RuleAdministration +RuleAdministration ruleAdministrator = ruleServiceProvider.getRuleAdministrator(); +LocalRuleExecutionSetProvider ruleExecutionSetProvider = ruleAdministrator.getLocalRuleExecutionSetProvider( null ); + +// Create a Reader for the drl +URL drlUrl = new URL("http://mydomain.org/sources/myrules.drl"); +Reader drlReader = new InputStreamReader( drlUrl.openStream() ); + +// Create a Reader for the dsl and a put in the properties map +URL dslUrl = new URL("http://mydomain.org/sources/myrules.dsl"); +Reader dslReader = new InputStreamReader( dslUrl.openStream() ); +Map properties = new HashMap(); +properties.put( "source", "drl" ); +properties.put( "dsl", dslReader ); + +// Create the RuleExecutionSet for the drl and dsl +RuleExecutionSet ruleExecutionSet = ruleExecutionSetProvider.createRuleExecutionSet( reader, properties ); +</programlisting> + </example> + + <para>When registering a RuleExecution set you must specify the name, to + be used for its retrieval. There is also a field to pass properties, this + is currently unused so just pass null.</para> + + <example> + <title>Register the RuleExecutionSet</title> + + <programlisting>// Register the RuleExecutionSet with the RuleAdministrator +String uri = ruleExectionSet.getName(); +ruleAdministrator.registerRuleExecutionSet(uri, ruleExecutionSet, null);</programlisting> + </example> </section> <section> - <title>Globals</title> + <title>Using Stateful and Stateless RuleSessions</title> - <para>You do not need to dispense with globals using Drools through the - Java Rule Enige API. They are as usual defined in your rule file (drl). - You need to ship them with the Map of properties to the Rule Engine - creating a stateful or stateless RuleSession. It works like the Domain - Specific Language for creating a RuleExecutionSet. The key you put in the - Map will be the identifier in the drl file. In the following example the - results are collected in an java.util.Vector which is used as - global:</para> + <para>The Runtime, obtained from the RuleExecutionSetProvider, is used to + create stateful and stateless rule engine sessions.</para> - <programlisting>java.util.Vector globalVector = new java.util.Vector( ); + <example> + <title>Getting the RuleRuntime</title> + + <programlisting>RuleRuntime ruleRuntime = ruleExecutionSetProvider.getRuleRuntime();</programlisting> + </example> + + <para>To create a rule session you must use one of the two RuleRuntime + public constants - "RuleRuntime.STATEFUL_SESSION_TYPE" and + "RuleRuntime.STATELESS_SESSION_TYPE" along with the uri to the + RuleExecutionSet you wish to instantiate a RuleSession for. The properties + map can be null, or it can be used to specify globals, as shown in the + next section. The createRuleSession(....) method returns a RuleSession + instance which must then be cast to StateFulRuleSession or + StatelessRuleSession.</para> + + <example> + <title>Stateful Rule</title> + + <programlisting>(StateFulRuleSession) session = ruleRuntime.createRuleSession( uri, + null, + RuleRuntime.STATEFUL_SESSION_TYPE ); +session.addObject( new PurchaseOrder( "lots of cheese" ) ); +session.executeObjects();</programlisting> + </example> + + <para>The StatelessRuleSession has a very simple API; you can only call + executeRules(List list) passing a list of objects, and an optional filter, + the resulting objects are then returned.</para> + + <example> + <title>Stateless</title> + + <programlisting>(StatelessRuleSession) session = ruleRuntime.createRuleSession( uri, + null, + RuleRuntime.STATELESS_SESSION_TYPE ); +List list = new ArrayList(); +list.add( new PurchaseOrder( "even more cheese" ) ); + +List results = new ArrayList(); +results = session.executeRules( list );</programlisting> + </example> + + <section> + <title>Globals</title> + + <para>It is possible to support globals with JSR94, in a none portable + manner, by using the propperties map passed to the RuleSession factory + method. Globals must be defined in the drl or xml file first, otherwise + an Exception will be thrown. the key represents the identifier declared + in the drl or xml and the value is the instance you wish to be used in + the execution. In the following example the results are collected in an + java.util.List which is used as global:</para> + + <programlisting>java.util.List globalList = new java.util.ArrayList( ); java.util.Map map = new java.util.HashMap( ); -map.put( "vector", globalVector ); +map.put( "list", globalList ); //Open a stateless Session StatelessRuleSession srs = (StatelessRuleSession) runtime.createRuleSession( "SistersRules", map, RuleRuntime.STATELESS_SESSION_TYPE ); ... // Persons added to List // call executeRules( ) giving a List of Objects as parameter -// There are rules which will put Objects in the Vector -// fetch the vector from the map -v = (java.util.Vector)map.get("vector");</programlisting> +// There are rules which will put Objects in the List +// fetch the list from the map +List list = (java.util.List) map.get("list");</programlisting> - <para>Do not forget to declare the global "vector" in your DRL:</para> + <para>Do not forget to declare the global "list" in your DRL:</para> - <programlisting>package SistersRules; + <programlisting>package SistersRules; import org.drools.jsr94.rules.Person; -global java.util.Vector vector +global java.util.List list rule FindSisters when $person1 : Person ( $name1:name ) $person2 : Person ( $name2:name ) eval( $person1.hasSister($person2) ) then -vector.add($person1.getName() + " and " + $person2.getName() +" are sisters"); +list.add($person1.getName() + " and " + $person2.getName() +" are sisters"); assert( $person1.getName() + " and " + $person2.getName() +" are sisters"); end</programlisting> + </section> </section> </section> \ No newline at end of file Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Introduction.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Introduction.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Introduction.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -1,40 +1,26 @@ -<?xml version="1.0" encoding="UTF-8"?> -<section> - <title>Introduction</title> - - <para>JBoss Rules comes with an own implementation for the Java Rule Engine - API (known as JSR94). The API allows you to change easier from your current - rule engine to JBoss Rules. If your code is making use of Java Rule Engine - API, you just need to change the implementation class, which you need to - give to the RuleServiceProviderManager, to use JBoss Rules as your rule - engine.</para> - - <para>Well, thus easy it is not, because there is not standarized Rule - Language, yet. You will have to translate existing rules to the Drools Rule - Language which is supported by JBoss Rules. W3C is planning a <ulink - url="http://www.w3.org/TR/2006/WD-rif-ucr-20060323/">Rule Interchange - Format (RIF)</ulink> and <ulink url="http://ruleml.org/">RuleML</ulink> is - as well an interesting candidate for a Standard Rule Language. Till there is - Standard Rule Language, which will be supported by JBoss Rules, you are - invited to contribute your transformer, which is transforming rule language - X to the Drools Rule Language. The transformer might be a script, class, - stylesheet or everything what is doing the job.</para> - - <para>The following sections deal with the use of the Java Rule Engine API. - There is a part which explains the specification and one how the Java Rule - Engine API can be used in example. If you know the specification, just skip - the specification section. There are some interesting links inside of the - references section giving you all the information about the Java Rule Engine - API you might need.</para> - - <para>Before you start complaining about that you need to write more code - and that there is less functionality than if you make use of the native - Drools API, it is mentioned now, that a standard represents everytime the - lcd (least common denominator) of the specification drivers. That - functionality which is common around all the rule engines.</para> - - <para>At the time of writing this documentation the JSR 94 implementation is - not supporting rules in XML and Domain Specific Languages. This will change - in one of the next releases. Please be appreciative of this fact and keep an - eye on the actual release notes.</para> -</section> +<?xml version="1.0" encoding="UTF-8"?> +<section> + <title>Introduction</title> + + <para>Drools provides an implementation of the Java Rule Engine API (known + as JSR94), which allows for support of multiple rule engines from a single + API. JSR94 does not deal in anyway with the rule language itself. W3C is + working on the <ulink + url="http://www.w3.org/TR/2006/WD-rif-ucr-20060323/">Rule Interchange Format + (RIF)</ulink> and the OMG has started to work on a standard based on <ulink + url="http://ruleml.org/">RuleML</ulink>, recently Haley Systems has also + proposed a rule alnguage standard called RML.</para> + + <para>It should be remembered that the JSR94 standard represents the "least + common denominator" in features across rule engines - this means there is + less functionality in the JSR94 api than in the standard Drools api. So by + using JSR94 you are restricting yourself in taking advantage of using the + full capabilities of the Drools Rule Engine. It is necessary to expose + further functionality, like globals and support for drl, dsl and xml via + properties maps due to the very basic feature set of JSR94 - this introduces + non portable functionality. Further to this, as JSR94 does not provide a + rule language, you are only solving a small fraction of the complexity of + switching rule engines with very little gain. So while we support JSR94, for + those that insist on using it, we strongly recommend you program against the + Drools API.</para> +</section> \ No newline at end of file Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-References.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-References.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-References.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -1,72 +1,68 @@ -<?xml version="1.0" encoding="UTF-8"?> -<section> - <title>References</title> - - <para>If you need more information on JSR 94, please refer to the following - references <orderedlist> - <listitem> - <para>Official JCP Specification for Java Rule Engine API (JSR - 94)</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.jcp.org/en/jsr/detail?id=94">http://www.jcp.org/en/jsr/detail?id=94</ulink></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>The Java Rule Engine API documentation</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.javarules.org/api_doc/api/index.html">http://www.javarules.org/api_doc/api/index.html</ulink></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>The Logic From The Bottom Line: An Introduction to The Drools - Project. By N. Alex Rupp, published on TheServiceSide.com in - 2004</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.theserverside.com/articles/article.tss?l=Drools">http://www.theserverside.com/articles/article.tss?l=Drools</ulink></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Getting Started With the Java Rule Engine API (JSR 94): Toward - Rule-Based Applications. By Dr. Qusay H. Mahmoud, published on Sun - Developer Network in 2005</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://java.sun.com/developer/technicalArticles/J2SE/JavaRule.html">http://java.sun.com/developer/technicalArticles/J2SE/JavaRule.html</ulink></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para>Jess and the javax.rules API. By Ernest Friedman-Hill, published - on TheServerSide.com in 2003</para> - - <itemizedlist> - <listitem> - <para><ulink - url="http://www.theserverside.com/articles/article.tss?l=Jess">http://www.theserverside.com/articles/article.tss?l=Jess</ulink></para> - </listitem> - </itemizedlist> - </listitem> - - <listitem> - <para></para> - </listitem> - </orderedlist></para> -</section> +<?xml version="1.0" encoding="UTF-8"?> +<section> + <title>References</title> + + <para>If you need more information on JSR 94, please refer to the following + references <orderedlist> + <listitem> + <para>Official JCP Specification for Java Rule Engine API (JSR + 94)</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.jcp.org/en/jsr/detail?id=94">http://www.jcp.org/en/jsr/detail?id=94</ulink></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>The Java Rule Engine API documentation</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.javarules.org/api_doc/api/index.html">http://www.javarules.org/api_doc/api/index.html</ulink></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>The Logic From The Bottom Line: An Introduction to The Drools + Project. By N. Alex Rupp, published on TheServiceSide.com in + 2004</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.theserverside.com/articles/article.tss?l=Drools">http://www.theserverside.com/articles/article.tss?l=Drools</ulink></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Getting Started With the Java Rule Engine API (JSR 94): Toward + Rule-Based Applications. By Dr. Qusay H. Mahmoud, published on Sun + Developer Network in 2005</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://java.sun.com/developer/technicalArticles/J2SE/JavaRule.html">http://java.sun.com/developer/technicalArticles/J2SE/JavaRule.html</ulink></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>Jess and the javax.rules API. By Ernest Friedman-Hill, published + on TheServerSide.com in 2003</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.theserverside.com/articles/article.tss?l=Jess">http://www.theserverside.com/articles/article.tss?l=Jess</ulink></para> + </listitem> + </itemizedlist> + </listitem> + </orderedlist></para> +</section> \ No newline at end of file Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Specification.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Specification.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/Chapter-JSR94/Section-Specification.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -1,328 +1,327 @@ -<?xml version="1.0" encoding="UTF-8"?> -<section> - <title>Specification</title> - - <para>This sections introduces the specification with the included packages - javax.rules and javax.rules.admin. If you have read this section, you should - know, which classes are included and what their purpose is.</para> - - <para>The Java Rule Engine API is divided in two packages. You use - "javax.rules" mainly for executing the rule engine and "javax.rules.admin" - for administration. </para> - - <section> - <title>javax.rules</title> - - <para>The next sections are dealing with the interfaces, classes and - exceptions which are included in the javax.rules package.</para> - - <section> - <title>Interfaces</title> - - <itemizedlist> - <listitem> - <para><interfacename>Handle</interfacename></para> - - <para>The Handle is needed to get an Object back from the - <classname>WorkingMemory</classname> , which was added there in a - <classname>StatefulRuleSession</classname> . With the - <classname>Handle</classname> you can modify or remove an - <classname>Object</classname> from the - <classname>WorkingMemory</classname> . To modify an Object call - <methodname>updateObject()</methodname> from the - <classname>StatefulRuleSession</classname> . To remove it, call - <methodname>removeObject()</methodname> with the - <classname>Handle</classname> as the Parameter. Inside of the - implementation of the Java Rule Engine API will be called the - <methodname>modifyObject()</methodname> and - <methodname>retractObject()</methodname> methods of the encapsulated - Drools API.</para> - </listitem> - - <listitem> - <para><interfacename>ObjectFilter</interfacename></para> - - <para>This interface is used to filter objects. If you give it to a - RuleSession, it will filter the output.</para> - </listitem> - - <listitem> - <para><interfacename>RuleExecutionSetMetadata</interfacename></para> - - <para>The RuleExecutionSetMetadata are keeping name, description and - URI of a RuleExecutionSet. Do not wonder, in the current - implementation name and description are the same.</para> - </listitem> - - <listitem> - <para><interfacename>RuleRuntime</interfacename></para> - - <para>The RuleRuntime is the key to a RuleSession. The RuleRuntime - you get from the RuleServiceProvider.</para> - - <para>If you got a RuleRuntime call createRuleSession() to open a - RuleSession.</para> - - <para>Through the RuleRuntime you can retrieve a list of URIs of all - RuleExecutionSets, which were registered by a RuleAdministrator. You - need the URI as a String to open a RuleSession to the rule engine. - The rule engine will use the rules of the RuleExecutionSet inside of - the RuleSession.</para> - - <para>Important: The Map is used for Globals. Globals were formerly - called ApplicationData (in Drools 2.x). The key needs to be the - identifier of the Global and the Value the object you want to use as - a Global.</para> - </listitem> - - <listitem> - <para><interfacename>RuleSession</interfacename></para> - - <para>The RuleSession is the object you are working with, if you - want to contact the rule engine.</para> - - <para>If you are getting a RuleSession from the RuleRuntime, then it - will be either a StatefulRuleSession or a - StatelessRuleSession.</para> - - <para>Please call in both cases the release()-method that all - resources will be freed.</para> - </listitem> - - <listitem> - <para><interfacename>StatefulRuleSession </interfacename></para> - - <para>A stateful Rule Session you are using, if you need to run the - rule engine more than once. You get the chance to assert objects, - execute rules, assert objects again etc..</para> - - <para>You will get a Handle for every object which you are asserting - to the Rule Session. Do not lose it, you will need it, to retract or - modify objects in the Working Memory. You are having no direct - contact to Drools´ Working Memory which is used inside the - implementation, for this you got the RuleSession.</para> - </listitem> - - <listitem> - <para><interfacename>StatelessRuleSession </interfacename></para> - - <para>A stateless RuleSession means, that you are having only one - contact to the rule engine. You are giving a list of objects to the - rule engine and the rule engine asserts them all and starts - execution immediately. The result is a list of objects. The content - of the result list depends on your rules. If your rules are not - modifying or retracting any objects from the Working Memory, you - should get all objects, you added back.</para> - - <para>There is a possibility using an ObjectFilter which will filter - the resulting list of objects before you get it.</para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Classes</title> - - <itemizedlist> - <listitem> - <para><classname>RuleServiceProvider</classname></para> - - <para>The RuleServiceProvider gives you the RuleAdministrator or a - RuleRuntime, which you need to open a new Rule Session. To get the - RuleServiceProvider call - RuleServiceProviderManager.getRuleServiceProvider().</para> - - <para>In J2EE environment you can bind the RuleServiceProvider to - the JNDI and make a lookup to get it in all your - applications.</para> - </listitem> - - <listitem> - <para><classname> RuleServiceProviderManager </classname></para> - - <para>The RuleServiceProvider is often compared with the - DriverManager, which you use in JDBC. It works like setting up the - Driver for a DataBase.</para> - - <para>To load the Drools Rule Service Provider use:</para> - - <para><code>Class ruleServiceProviderClass = - Class.forName("org.drools.jsr94.rules.RuleServiceProviderImpl");</code></para> - - <para>If you did not register it, yet, do it now:</para> - - <para><code>RuleServiceProviderManager.registerRuleServiceProvider( - "http://jboss.com/products/rules", ruleServiceProviderClass); - </code></para> - - <para>Now you can get your RuleServiceProvider calling:</para> - - <para><code>RuleServiceProviderManager.getRuleServiceProvider("http://jboss.com/products/rules")</code>;</para> - - <para>If you do not need the RuleServiceProvider any more, - deregister it:</para> - - <para><code>RuleServiceProviderManager.deregisterRuleServiceProvider( - "http://jboss.com/products/rules"); </code></para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Exceptions</title> - - <itemizedlist> - <listitem> - <para><classname>ConfigurationException</classname></para> - - <para>This exception is thrown when a user configuration error has - been made.</para> - </listitem> - - <listitem> - <para><classname>InvalidHandleException</classname></para> - - <para>This exception is thrown when a client passes an invalid - Handle to the rule engine.</para> - </listitem> - - <listitem> - <para><classname> InvalidRuleSessionException </classname></para> - - <para>The InvalidRuleSessionException should be thrown when a method - is invoked on a RuleSession and the internal state of the - RuleSession is invalid. This may have occured because a - StatefulRuleSession has been serialized and external resources can - no longer be accessed. This exception is also used to signal that a - RuleSession is in an invalid state (such as an attempt to use it - after the release method has been called) (Taken from JCP API - Documentation).</para> - </listitem> - - <listitem> - <para><classname>RuleException</classname></para> - - <para>Base class for all Exception classes in the javax.rules - package (Taken from JCP API Documentation).</para> - </listitem> - - <listitem> - <para><classname>RuleExecutionException</classname></para> - - <para>This exception is not thrown in the Drools 3 JSR 94 - implementation</para> - </listitem> - - <listitem> - <para><classname> RuleExecutionSetNotFoundException - </classname></para> - - <para>This exception is thrown if a client requests a - RuleExecutionSet from the RuleRuntime and the URI or - RuleExecutionSet cannot be found (Taken from JCP API - Documentation).</para> - </listitem> - - <listitem> - <para><classname> RuleSessionCreateException </classname></para> - - <para>This exception is thrown when a client requests a RuleSession - from the RuleRuntime and an error occurs that prevents a RuleSession - from being returned (Taken from JCP API Documentation).</para> - </listitem> - - <listitem> - <para><classname> RuleSessionTypeUnsupportedException - </classname></para> - - <para>This exception is thrown when a client requests a RuleSession - and the vendor does not support the given type (defined in the - RuleRuntime) or the RuleExecutionSet itself does not support the - requested mode (Taken from JCP API Documentation).</para> - </listitem> - </itemizedlist> - </section> - </section> - - <section> - <title>javax.rules.admin</title> - - <para>In this section all the interfaces and exceptions from the - javax.rules.admin package are explained.</para> - - <section> - <title>Interfaces</title> - - <itemizedlist> - <listitem> - <para><interfacename>LocalRuleExecutionSetProvider</interfacename></para> - - <para></para> - </listitem> - - <listitem> - <para><interfacename>Rule</interfacename></para> - - <para></para> - </listitem> - - <listitem> - <para><interfacename>RuleAdministrator</interfacename></para> - - <para></para> - </listitem> - - <listitem> - <para><interfacename>RuleExecutionSet</interfacename></para> - - <para></para> - </listitem> - - <listitem> - <para><interfacename>RuleExecutionSetProvider</interfacename></para> - - <para></para> - </listitem> - </itemizedlist> - </section> - - <section> - <title>Exceptions</title> - - <itemizedlist> - <listitem> - <para><classname>RuleAdministrationException</classname></para> - - <para>Base class for all administration RuleException classes in the - javax.rules.admin package (Taken from JCP API Documentation).</para> - </listitem> - - <listitem> - <para><classname> RuleExecutionSetCreateException - </classname></para> - - <para>This exception is thrown if an error occurs while creating a - rule execution set (Taken from JCP API Documentation).</para> - </listitem> - - <listitem> - <para><classname> RuleExecutionSetDeregistrationException - </classname></para> - - <para>This exception is thrown if an exception occurs while - unregistering a rule execution set from a URI (Taken from JCP API - Documentation).</para> - </listitem> - - <listitem> - <para><classname> RuleExecutionSetRegisterException - </classname></para> - - <para>This exception is thrown if an exception occurs while - registering a rule execution set to a URI (Taken from JCP API - Documentation).</para> - </listitem> - </itemizedlist> - </section> - </section> -</section> +<?xml version="1.0" encoding="UTF-8"?> +<section> + <title>Specification</title> + + <para>This sections introduces the specification with the included packages + javax.rules and javax.rules.admin. If you have read this section, you should + know, which classes are included and what their purpose is.</para> + + <para>The Java Rule Engine API is divided in two packages. You use + "javax.rules" mainly for executing the rule engine and "javax.rules.admin" + for administration.</para> + + <section> + <title>javax.rules</title> + + <para>The next sections are dealing with the interfaces, classes and + exceptions which are included in the javax.rules package.</para> + + <section> + <title>Interfaces</title> + + <itemizedlist> + <listitem> + <para><interfacename>Handle</interfacename></para> + + <para>The Handle is used to retrieve an Object back from the + <classname>WorkingMemory</classname> , which was added there in a + <classname>StatefulRuleSession</classname> . With the + <classname>Handle</classname> you can modify or remove an + <classname>Object</classname> from the + <classname>WorkingMemory</classname> . To modify an Object call + <methodname>updateObject()</methodname> from the + <classname>StatefulRuleSession</classname> . To remove it, call + <methodname>removeObject()</methodname> with the + <classname>Handle</classname> as the Parameter. Inside of the + implementation of the Java Rule Engine API will be called the + <methodname>modifyObject()</methodname> and + <methodname>retractObject()</methodname> methods of the encapsulated + Drools API.</para> + </listitem> + + <listitem> + <para><interfacename>ObjectFilter</interfacename></para> + + <para>This interface is used to filter objects for + RuleSession.</para> + </listitem> + + <listitem> + <para><interfacename>RuleExecutionSetMetadata</interfacename></para> + + <para>The RuleExecutionSetMetadata is used to store name, + description and URI for a RuleExecutionSet.</para> + </listitem> + + <listitem> + <para><interfacename>RuleRuntime</interfacename></para> + + <para>The RuleRuntime is the key to a RuleSession. The RuleRuntime + obtained from the RuleServiceProvider.</para> + + <para>If you retrieve a RuleRuntime call createRuleSession() to open + a RuleSession.</para> + + <para>Through the RuleRuntime you can retrieve a list of URIs of all + RuleExecutionSets, which were registered by a RuleAdministrator. You + need the URI as a String to open a RuleSession to the rule engine. + The rule engine will use the rules of the RuleExecutionSet inside of + the RuleSession.</para> + + <para>Important: The Map is used for Globals. Globals were formerly + called ApplicationData (in Drools 2.x). The key needs to be the + identifier of the Global and the Value the object you want to use as + a Global.</para> + </listitem> + + <listitem> + <para><interfacename>RuleSession</interfacename></para> + + <para>The RuleSession is the object you are working with, if you + want to contact the rule engine.</para> + + <para>If you are getting a RuleSession from the RuleRuntime, then it + will be either a StatefulRuleSession or a + StatelessRuleSession.</para> + + <para>Please call in both cases the release()-method that all + resources will be freed.</para> + </listitem> + + <listitem> + <para><interfacename>StatefulRuleSession </interfacename></para> + + <para>A stateful Rule Session you are using, if you need to run the + rule engine more than once. You get the chance to assert objects, + execute rules, assert objects again etc..</para> + + <para>You will get a Handle for every object which you are asserting + to the Rule Session. Do not lose it, you will need it, to retract or + modify objects in the Working Memory. You are having no direct + contact to Drools´ Working Memory which is used inside the + implementation, for this you got the RuleSession.</para> + </listitem> + + <listitem> + <para><interfacename>StatelessRuleSession </interfacename></para> + + <para>A stateless RuleSession means, that you are having only one + contact to the rule engine. You are giving a list of objects to the + rule engine and the rule engine asserts them all and starts + execution immediately. The result is a list of objects. The content + of the result list depends on your rules. If your rules are not + modifying or retracting any objects from the Working Memory, you + should get all objects, you added back.</para> + + <para>There is a possibility using an ObjectFilter which will filter + the resulting list of objects before you get it.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Classes</title> + + <itemizedlist> + <listitem> + <para><classname>RuleServiceProvider</classname></para> + + <para>The RuleServiceProvider gives you the RuleAdministrator or a + RuleRuntime, which you need to open a new Rule Session. To get the + RuleServiceProvider call + RuleServiceProviderManager.getRuleServiceProvider().</para> + + <para>In J2EE environment you can bind the RuleServiceProvider to + the JNDI and make a lookup to get it in all your + applications.</para> + </listitem> + + <listitem> + <para><classname> RuleServiceProviderManager </classname></para> + + <para>The RuleServiceProvider is often compared with the + DriverManager, which you use in JDBC. It works like setting up the + Driver for a DataBase.</para> + + <para>To load the Drools Rule Service Provider use:</para> + + <para><code>Class ruleServiceProviderClass = + Class.forName("org.drools.jsr94.rules.RuleServiceProviderImpl");</code></para> + + <para>If you did not register it, yet, do it now:</para> + + <para><code>RuleServiceProviderManager.registerRuleServiceProvider( + "http://jboss.com/products/rules", ruleServiceProviderClass); + </code></para> + + <para>Now you can get your RuleServiceProvider calling:</para> + + <para><code>RuleServiceProviderManager.getRuleServiceProvider("http://jboss.com/products/rules")</code>;</para> + + <para>If you do not need the RuleServiceProvider any more, + deregister it:</para> + + <para><code>RuleServiceProviderManager.deregisterRuleServiceProvider( + "http://jboss.com/products/rules"); </code></para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Exceptions</title> + + <itemizedlist> + <listitem> + <para><classname>ConfigurationException</classname></para> + + <para>This exception is thrown when a user configuration error has + been made.</para> + </listitem> + + <listitem> + <para><classname>InvalidHandleException</classname></para> + + <para>This exception is thrown when a client passes an invalid + Handle to the rule engine.</para> + </listitem> + + <listitem> + <para><classname> InvalidRuleSessionException </classname></para> + + <para>The InvalidRuleSessionException should be thrown when a method + is invoked on a RuleSession and the internal state of the + RuleSession is invalid. This may have occured because a + StatefulRuleSession has been serialized and external resources can + no longer be accessed. This exception is also used to signal that a + RuleSession is in an invalid state (such as an attempt to use it + after the release method has been called) (Taken from JCP API + Documentation).</para> + </listitem> + + <listitem> + <para><classname>RuleException</classname></para> + + <para>Base class for all Exception classes in the javax.rules + package (Taken from JCP API Documentation).</para> + </listitem> + + <listitem> + <para><classname>RuleExecutionException</classname></para> + + <para>This exception is not thrown in the Drools 3 JSR 94 + implementation</para> + </listitem> + + <listitem> + <para><classname> RuleExecutionSetNotFoundException + </classname></para> + + <para>This exception is thrown if a client requests a + RuleExecutionSet from the RuleRuntime and the URI or + RuleExecutionSet cannot be found (Taken from JCP API + Documentation).</para> + </listitem> + + <listitem> + <para><classname> RuleSessionCreateException </classname></para> + + <para>This exception is thrown when a client requests a RuleSession + from the RuleRuntime and an error occurs that prevents a RuleSession + from being returned (Taken from JCP API Documentation).</para> + </listitem> + + <listitem> + <para><classname> RuleSessionTypeUnsupportedException + </classname></para> + + <para>This exception is thrown when a client requests a RuleSession + and the vendor does not support the given type (defined in the + RuleRuntime) or the RuleExecutionSet itself does not support the + requested mode (Taken from JCP API Documentation).</para> + </listitem> + </itemizedlist> + </section> + </section> + + <section> + <title>javax.rules.admin</title> + + <para>In this section all the interfaces and exceptions from the + javax.rules.admin package are explained.</para> + + <section> + <title>Interfaces</title> + + <itemizedlist> + <listitem> + <para><interfacename>LocalRuleExecutionSetProvider</interfacename></para> + + <para></para> + </listitem> + + <listitem> + <para><interfacename>Rule</interfacename></para> + + <para></para> + </listitem> + + <listitem> + <para><interfacename>RuleAdministrator</interfacename></para> + + <para></para> + </listitem> + + <listitem> + <para><interfacename>RuleExecutionSet</interfacename></para> + + <para></para> + </listitem> + + <listitem> + <para><interfacename>RuleExecutionSetProvider</interfacename></para> + + <para></para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Exceptions</title> + + <itemizedlist> + <listitem> + <para><classname>RuleAdministrationException</classname></para> + + <para>Base class for all administration RuleException classes in the + javax.rules.admin package (Taken from JCP API Documentation).</para> + </listitem> + + <listitem> + <para><classname> RuleExecutionSetCreateException + </classname></para> + + <para>This exception is thrown if an error occurs while creating a + rule execution set (Taken from JCP API Documentation).</para> + </listitem> + + <listitem> + <para><classname> RuleExecutionSetDeregistrationException + </classname></para> + + <para>This exception is thrown if an exception occurs while + unregistering a rule execution set from a URI (Taken from JCP API + Documentation).</para> + </listitem> + + <listitem> + <para><classname> RuleExecutionSetRegisterException + </classname></para> + + <para>This exception is thrown if an exception occurs while + registering a rule execution set to a URI (Taken from JCP API + Documentation).</para> + </listitem> + </itemizedlist> + </section> + </section> +</section> \ No newline at end of file Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -34,10 +34,12 @@ <para>A RuleBase is a runtime component which consists of one or more Package's. Packages can be added and removed from the RuleBase at any time. A Rule Base can instantiate one or more WorkingMemories at any time; - a weak reference is maintained, unless its told otherwise. The Working - Memory consists of a number of sub components. XXXX Object assertion may - result in the creation of one or more Activations, the agenda is - resonpsible for scheduling the execution of these Activations</para> + a weak reference is maintained, unless it's told otherwise. The Working + Memory consists of a number of sub components inculding Working Memory + Event Support, Truth Maintenance System, Agenda and Agenda Event Support. + Object assertion may result in the creation of one or more Activations, + the agenda is resonpsible for scheduling the execution of these + Activations.</para> <figure> <title>Runtime Components</title> @@ -272,7 +274,7 @@ means ALL of the work is done during assertion; however, no rules are executedl you call "fireAllRules()" after you have finished asserting your facts. This is a common misunderstanding by people who think the - work happens when you call "fireAllRules()". </para> + work happens when you call "fireAllRules()".</para> <para>When an Object is asserted it returns a FactHandle. This FactHandle is the token used to represent your asserted Object inside @@ -283,14 +285,14 @@ FactHandle stiltonHandle = workingMemory.assertObject( stilton );</programlisting> <para>As mentioned in the Rule Base section a Working Memory may operate - in two assertions modes equality and identity - identity is default. - </para> + in two assertions modes equality and identity - identity is + default.</para> <para>Identity means the Working Memory uses an IdentityHashMap to store all asserted Objects. New instance assertions always result in the return of a new FactHandle, if an instance is asserted twice then it returns the previous fact handle – i.e. it ignores the second assertion - for the same fact. </para> + for the same fact.</para> <para>Equality means the Working Memory uses a HashMap to store all asserted Objects. New instance assertions will only return a new @@ -466,7 +468,7 @@ facts, and placed onto the Agenda. The Agenda controls the execution order of these Activations using a Conflict Resolution strategy.</para> - <para>The engine operates in a "2 phase" mode which is recursive: </para> + <para>The engine operates in a "2 phase" mode which is recursive:</para> <orderedlist> <listitem> @@ -481,7 +483,7 @@ <para>Agenda Evaluation - attempts to select a rule to fire, if a rule is not found it exits otherwise it attempts to fire the rule switching the phase back to Working Memory Actions and the process begins again - until the Agenda is empty. </para> + until the Agenda is empty.</para> </listitem> </orderedlist> Modified: labs/jbossrules/trunk/documentation/manual/en/master.xml =================================================================== --- labs/jbossrules/trunk/documentation/manual/en/master.xml 2006-07-07 14:44:59 UTC (rev 4944) +++ labs/jbossrules/trunk/documentation/manual/en/master.xml 2006-07-07 17:41:07 UTC (rev 4945) @@ -131,7 +131,8 @@ <xi:include href="Chapter-JSR94/Section-Introduction.xml" /> - <xi:include href="Chapter-JSR94/Section-Specification.xml" /> + <!-- Removed till it can be completed --> + <!-- include href="Chapter-JSR94/Section-Specification.xml" /--> <xi:include href="Chapter-JSR94/Section-How_To_Use.xml" /> |
