[jboss-svn-commits] JBL Code SVN: r24038 - in labs/jbossrules/trunk/drools-api/src/main/java/org/drools: runtime and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Nov 21 12:20:19 EST 2008
Author: mark.proctor at jboss.com
Date: 2008-11-21 12:20:18 -0500 (Fri, 21 Nov 2008)
New Revision: 24038
Modified:
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/definition/KnowledgePackage.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatelessKnowledgeSession.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatelessProcessSession.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatelessRuleSession.java
Log:
-more javadocs
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/definition/KnowledgePackage.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/definition/KnowledgePackage.java 2008-11-21 17:14:28 UTC (rev 24037)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/definition/KnowledgePackage.java 2008-11-21 17:20:18 UTC (rev 24038)
@@ -7,7 +7,7 @@
/**
* This provides a collection of knowledge definitions that can be given to a KnowledgeBase.
- * The name is used to provide "namespace" spearation of those defintions
+ * The name is used to provide "namespace" spearation of those definitions.
*
*
*/
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatelessKnowledgeSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatelessKnowledgeSession.java 2008-11-21 17:14:28 UTC (rev 24037)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatelessKnowledgeSession.java 2008-11-21 17:20:18 UTC (rev 24038)
@@ -1,9 +1,106 @@
package org.drools.runtime;
+import java.io.InputStreamReader;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.drools.KnowledgeBase;
+import org.drools.KnowledgeBaseFactory;
+import org.drools.builder.KnowledgeBuilder;
+import org.drools.builder.KnowledgeBuilderFactory;
+import org.drools.builder.KnowledgeType;
+import org.drools.definition.KnowledgePackage;
import org.drools.event.KnowledgeRuntimeEventManager;
import org.drools.runtime.process.StatelessProcessSession;
import org.drools.runtime.rule.StatelessRuleSession;
+/**
+ * StatelessKnowledgeSessions are convenience api, that wraps a StatefulKonwledgeSession. It removes the need to
+ * call dispose(), as well as providing support for execution parameters. Stateless sessions do not support
+ * iterative insertions and fireAllRules from java code, the act of calling executeObject() or executeIterable() is a single
+ * shot method that will internally instantiate a StatefullKnowledgeSession, add all the user data, call fireAllRules, and then
+ * call dispose(). Additionally to this convenience it also adds additional functionality via the use of Parameters.
+ *
+ * <p>
+ * Simple example showing a stateless session executing for a given collection of java objects.
+ * </p>
+ * <pre>
+ * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ * kbuilder.addResource( new InputStreamReader( getClass().getResourceAsStream( fileName ) ), KnowledgeType.DRL );
+ * assertFalse( kbuilder.hasErrors() );
+ * if (kbuilder.hasErrors() ) {
+ * System.out.println( kbuilder.getErrors() );
+ * }
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );
+ * </pre>
+ *
+ * StatelessKnowledgeSession session = kbase.newStatelessKnowledgeSession();
+ * session.executeIterable( collection );
+ * </pre>
+ *
+ * <p>
+ * StatelessKnowledgeSessions support globals, scoped in a number of ways. I'll cover the non-parameter way first,
+ * as parameters are scoped to a specific execution call. Globals can be resolved in three ways. The StatelessKnowledgeSession
+ * supports setGlobalResolver() and setGlobal(). These globals are shared for ALL execution calls, so be especially careful of mutable
+ * globals in these cases - as often execution calls can be executing simultaneously in different threads.
+ * Calling of setGlobal(String, Object) will actually be set on an internal Collection, identifiers in this internal
+ * Collection will have priority over the externally supplied GlobalResolver. If an identifier cannot be found in
+ * the internal Collection, it will then check the externally supplied Global Resolver, if one has been set.
+ * </p>
+ *
+ * <p>code snippet for setting a global:</p>
+ * <pre>
+ * StatelessKnowledgeSession session = kbase.newStatelessKnowledgeSession();
+ * session.setGlobal( "hbnSession", hibernateSession ); // sets a global hibernate session, that can be used for DB interactions in the rules.
+ * session.executeIterable( collection ); // this will now execute and will be able to resolve the "hbnSession" identifier.
+ * </pre>
+ *
+ * <p>
+ * Stateless sessions also support in, out, inOut parameters. These parameters and their values are scoped to the execution call they are used in.
+ * All external variables in Drools stateless sessions are represented by globals in the drl. The in, out, inOut parameters are effectively mappings
+ * to these globals. To work with parameters the Parameters class must be used. in, out, inOut parameters can be used for Globals and for Facts.
+ * </p>
+ *
+ * <p>This example shows the setting of both an in and an out global, as well as both an in and an out fact.</p>
+ * <pre>
+ * Parameters parameters = session.newParameters();
+ * Map<String, Object> globalsIn = new HashMap<String, Object>();
+ * globalsIn.put( "inString", "string" );
+ * parameters.getGlobalParams().setIn( globalsIn );
+ * parameters.getGlobalParams().setOut( Arrays.asList( new String[]{"list"} ) );
+ *
+ * Map<String, Object> factIn = new HashMap<String, Object>();
+ * factIn.put( "inCheese", cheddar );
+ * parameters.getFactParams().setIn( factIn );
+ * parameters.getFactParams().setOut( Arrays.asList( new String[]{ "outCheese"} ) );
+ *
+ * StatelessKnowledgeSessionResults results = session.executeObjectWithParameters( collection, // these facts are anonymous
+ * parameters );
+ * </pre>
+ * <p>
+ * A created and inserted fact, from inside of the engine, is not automatically associated with an out parameter - there is no way for the engine
+ * to infer this information. So it is up to the user to do this mapping manually. The following code snippet demonstrates how to do this, for the above
+ * "outCheese" parameter:
+ * </p>
+ * <pre>
+ * global Cheese outCheese
+ *
+ * rule "out example"
+ * when
+ * ...
+ * then
+ * Cheese brie = new Cheese("brie", 50);
+ * insert( brie );
+ * drools.getWorkingMemory().setGlobal("outCheese", brie);
+ * end
+ * </pre>
+ *
+ * @see org.drools.runtime.Parameters
+ * @see org.drools.runtime.GlobalResolver
+ */
public interface StatelessKnowledgeSession
extends
StatelessRuleSession,
@@ -11,13 +108,13 @@
KnowledgeRuntimeEventManager {
/**
- * Delegate used to resolve any global names not found in the global map.
+ * Delegate used to resolve any global names not found in the internally collection.
* @param globalResolver
*/
void setGlobalResolver(GlobalResolver globalResolver);
/**
- * Sets a global value
+ * Sets a global value on the iternal collection
* @param identifer
* @param value
*/
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatelessProcessSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatelessProcessSession.java 2008-11-21 17:14:28 UTC (rev 24037)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatelessProcessSession.java 2008-11-21 17:20:18 UTC (rev 24038)
@@ -1,5 +1,11 @@
package org.drools.runtime.process;
+/**
+ * There are currently no process related methods that are used with the external StatelessKnowledgeSession class. So this
+ * interface is just a marker at the moment, but may find more uses in the future as requirements are discovered.
+ *
+ * @see org.drools.runtime.StatelessKnowledgeSession
+ */
public interface StatelessProcessSession {
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatelessRuleSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatelessRuleSession.java 2008-11-21 17:14:28 UTC (rev 24037)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatelessRuleSession.java 2008-11-21 17:20:18 UTC (rev 24038)
@@ -3,16 +3,52 @@
import org.drools.runtime.Parameters;
import org.drools.runtime.StatelessKnowledgeSessionResults;
+/**
+ * This interface is used as part of the StatelessKnowledSession, which is the interface returned from the KnowledgeBase.
+ * Please see StatelessKnowledSession for more details on how to use this api.
+ *
+ * @see org.drools.runtime.StatelessKnowledgeSession
+ */
public interface StatelessRuleSession {
+
+ /**
+ * Execute a StatelessKnowledSession inserting just a single object. If a collection (or any other Iterable) or an array is used here, it will be inserted as-is,
+ * It will not be iterated and it's internal elements inserted.
+ *
+ * @param object
+ */
void executeObject(Object object);
+ /**
+ * Execute a StatelessKnowledSession, iterate the Iterable inserting each of it's elements. If you have an array, use the Arrays.asList(...) method
+ * to make that array Iterable.
+ * @param objects
+ */
void executeIterable(Iterable< ? > objects);
+ /**
+ * Will execute as with executeObject, but also allows the use of the Parameters class.
+ *
+ * @param object
+ * @param parameters
+ * @return
+ */
StatelessKnowledgeSessionResults executeObjectWithParameters(Object object,
Parameters parameters);
+ /**
+ * Will execute as with executeIterable, but also allows the use of the Parameters class.
+ *
+ * @param objects
+ * @param parameters
+ * @return
+ */
StatelessKnowledgeSessionResults executeIterableWithParameters(Iterable< ? > objects,
Parameters parameters);
+ /**
+ * Factory method to create and return a Parameters instance, which can be used to pass in, out, inOut parameters to an execution call.
+ * @return
+ */
Parameters newParameters();
}
More information about the jboss-svn-commits
mailing list