[jboss-svn-commits] JBL Code SVN: r24043 - in labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime: rule and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Nov 21 17:12:09 EST 2008
Author: tirelli
Date: 2008-11-21 17:12:09 -0500 (Fri, 21 Nov 2008)
New Revision: 24043
Modified:
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatefulKnowledgeSession.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/rule/StatefulRuleSession.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemory.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemoryEntryPoint.java
Log:
Adding javadocs
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatefulKnowledgeSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatefulKnowledgeSession.java 2008-11-21 22:10:05 UTC (rev 24042)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatefulKnowledgeSession.java 2008-11-21 22:12:09 UTC (rev 24043)
@@ -4,12 +4,71 @@
import org.drools.runtime.process.StatefulProcessSession;
import org.drools.runtime.rule.StatefulRuleSession;
+/**
+ * StatefulKnowledgeSession is the most common way to interact with a rules engine. A StatefulKnowledgeSession
+ * allows the application to establish an iterative conversation with the engine, where the reasoning process
+ * may be triggered multiple times for the same set of data. After the application finishes using the session,
+ * though, it <b>must</b> call the <code>dispose()</code> method in order to free the resources and used memory.
+ *
+ * <p>
+ * Simple example showing a stateful 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() );
+ *
+ * StatefulKnowledgeSession session = kbase.newStatelessKnowledgeSession();
+ * for( Object fact : facts ) {
+ * session.insert( fact );
+ * }
+ * session.fireAllRules();
+ * session.dispose();
+ * </pre>
+ *
+ * <p>
+ * StatefulKnowledgeSessions support globals. Globals are used to pass information into the engine and receive callbacks
+ * from your rules, but they should not be used to reason over. If you need to reason over your data, make sure you insert
+ * it as a fact, not a global.</p>
+ * <p>Globals are shared among ALL your rules, so be especially careful of (and avoid as much as possible) mutable globals.
+ * Also, it is a good practice to set your globals before inserting your facts. Rules engines evaluate rules at fact insertion
+ * time, and so, if you are using a global to constraint a fact pattern, and the global is not set, you may receive a
+ * <code>NullPointerException</code>. </p>
+ * <p>Globals can be resolved in two ways. The StatefulKnowledgeSession supports setGlobalResolver() and setGlobal().
+ * Calling of setGlobal(String, Object) will set the global 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>
+ * StatefulKnowledgeSession session = kbase.newStatefulKnowledgeSession();
+ * session.setGlobal( "hbnSession", hibernateSession ); // sets a global hibernate session, that can be used for DB interactions in the rules.
+ * for( Object fact : facts ) {
+ * session.insert( fact );
+ * }
+ * session.fireAllRules(); // this will now execute and will be able to resolve the "hbnSession" identifier.
+ * session.dispose();
+ * </pre>
+ *
+ * @see org.drools.runtime.GlobalResolver
+ */
public interface StatefulKnowledgeSession
extends
StatefulRuleSession,
StatefulProcessSession,
KnowledgeRuntime {
+ /**
+ * Sets a global value on the internal collection
+ * @param identifer the global identifier
+ * @param value the value assigned to the global identifier
+ */
void setGlobal(String identifier,
Object object);
@@ -19,7 +78,17 @@
*/
void setGlobalResolver(GlobalResolver globalResolver);
+ /**
+ * Returns the KnowledgeBase reference from which this stateful session was created.
+ *
+ * @return
+ */
KnowledgeBase getKnowledgeBase();
+ /**
+ * Releases all the current session resources, setting up the session for garbage collection.
+ * This method <b>must</b> always be called after finishing using the session, or the engine
+ * will not free the memory used by the session.
+ */
void dispose();
}
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 22:10:05 UTC (rev 24042)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/StatelessKnowledgeSession.java 2008-11-21 22:12:09 UTC (rev 24043)
@@ -1,17 +1,5 @@
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;
@@ -35,7 +23,6 @@
* }
* KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
* kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );
- * </pre>
*
* StatelessKnowledgeSession session = kbase.newStatelessKnowledgeSession();
* session.executeIterable( collection );
@@ -114,9 +101,9 @@
void setGlobalResolver(GlobalResolver globalResolver);
/**
- * Sets a global value on the iternal collection
- * @param identifer
- * @param value
+ * Sets a global value on the internal collection
+ * @param identifer the global identifier
+ * @param value the value assigned to the global identifier
*/
void setGlobal(String identifer,
Object value);
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatefulRuleSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatefulRuleSession.java 2008-11-21 22:10:05 UTC (rev 24042)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/StatefulRuleSession.java 2008-11-21 22:12:09 UTC (rev 24043)
@@ -1,5 +1,13 @@
package org.drools.runtime.rule;
+/**
+ * A super-interface for all <code>StatefulRuleSession</code>s.
+ * Although, users are encouraged to use <code>StatefulSession</code> interface instead of
+ * <code>WorkingMemory</code> interface, specially because of the <code>dispose()</code> method
+ * that is only available in the <code>StatefulKnowledgeSession</code> interface.
+ *
+ * @see org.drools.runtime.StatefulKnowledgeSession
+ */
public interface StatefulRuleSession
extends
WorkingMemory {
@@ -12,6 +20,19 @@
int fireAllRules();
/**
+ * Fire Activations on the Agenda up to the given maximum number of activations, before returning
+ * the control to the application.
+ * In case the application wants to continue firing the rules later, from the point where it stopped,
+ * it just needs to call <code>fireAllRules()</code> again.
+ *
+ * @param max
+ * the maximum number of rules that should be fired
+ * @return
+ * returns the number of rules fired
+ */
+ int fireAllRules(int max);
+
+ /**
* Fire all Activations on the Agenda
*
* @param agendaFilter
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemory.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemory.java 2008-11-21 22:10:05 UTC (rev 24042)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemory.java 2008-11-21 22:12:09 UTC (rev 24043)
@@ -6,28 +6,95 @@
import org.drools.runtime.ObjectFilter;
import org.drools.time.SessionClock;
+/**
+ * The <code>WorkingMemory</code> is a super-interface for all <code>StatefulKnowledgeSession</code>s.
+ * Although, users are encouraged to use <code>StatefulSession</code> interface instead of
+ * <code>WorkingMemory</code> interface, specially because of the <code>dispose()</code> method
+ * that is only available in the <code>StatefulKnowledgeSession</code> interface.
+ *
+ * @see org.drools.runtime.StatefulKnowledgeSession
+ */
public interface WorkingMemory
extends
WorkingMemoryEventManager,
WorkingMemoryEntryPoint {
+ /**
+ * <p>Request the engine to stop firing rules. If the engine is currently firing a rule, it will
+ * finish executing this rule's consequence before stopping.</p>
+ * <p>This method will not remove active activations from the Agenda.
+ * In case the application later wants to continue firing rules from the point where it stopped,
+ * it should just call <code>org.drools.runtime.StatefulKnowledgeSession.fireAllRules()</code> or
+ * <code>org.drools.runtime.StatefulKnowledgeSession.fireUntilHalt()</code> again.</p>
+ */
void halt();
/**
- * Returns the session clock instance associated with this session
+ * Returns the session clock instance assigned to this session
* @return
*/
public SessionClock getSessionClock();
+ /**
+ * Returns the fact handle associated with the given object. It is important to note that this
+ * method behaves in accordance with the configured assert behaviour for this knowledge base
+ * (either IDENTITY or EQUALITY).
+ *
+ * @param object
+ * the fact for which the fact handle will be returned.
+ *
+ * @return the fact handle for the given object, or null in case no fact handle was found for the
+ * given object.
+ *
+ * @see KnowledgeBaseConfiguration
+ */
FactHandle getFactHandle(Object object);
+ /**
+ * Returns all facts from the current session.
+ *
+ * @return
+ */
Collection< ? > getObjects();
+ /**
+ * Returns all facts from the current session that are accepted by the given <code>ObjectFilter</code>.
+ *
+ * @param filter the filter to be applied to the returned collection of facts.
+ *
+ * @return
+ */
Collection< ? > getObjects(ObjectFilter filter);
+ /**
+ * Returns all <code>FactHandle</code>s from the current session.
+ *
+ * @return
+ */
Collection< ? extends FactHandle> getFactHandles();
+ /**
+ * Returns all <code>FactHandle</code>s from the current session for which the facts are accepted by
+ * the given filter.
+ *
+ * @param filter the filter to be applied to the returned collection of <code>FactHandle</code>s.
+ *
+ * @return
+ */
Collection< ? extends FactHandle> getFactHandles(ObjectFilter filter);
+ /**
+ * Returns a reference to this session's <code>Agenda</code>.
+ *
+ * @return
+ */
Agenda getAgenda();
+
+ /**
+ * Returns the WorkingMemoryEntryPoint instance associated with the given name.
+ *
+ * @param name
+ * @return
+ */
+ WorkingMemoryEntryPoint getWorkingMemoryEntryPoint(String name);
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemoryEntryPoint.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemoryEntryPoint.java 2008-11-21 22:10:05 UTC (rev 24042)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/rule/WorkingMemoryEntryPoint.java 2008-11-21 22:12:09 UTC (rev 24043)
@@ -1,13 +1,58 @@
package org.drools.runtime.rule;
+/**
+ * <p>An entry-point is an abstract channel through where facts are inserted into the engine.</p>
+ * <p>Drools 5 supports multiple entry-points into a single <code>StatefulKnowledgeBase</code>: the
+ * default, anonymous entry-point, as well as as many user declared entry points the application
+ * requires.</p>
+ *
+ * <p>To get a reference to an entry point, just request the session:</p>
+ * <pre>
+ * StatefulKnowledgeSession session = kbase.newStatelessKnowledgeSession();
+ * ...
+ * WorkingMemoryEntryPoint entrypoint = session.getWorkingMemoryEntryPoint("my entry point");
+ * </pre>
+ * <p>Once a reference to an entry point is acquired, the application can insert, update and retract facts
+ * to/from that entry-point as usual:</p>
+ * <pre>
+ * ...
+ * FactHandle factHandle = entrypoint.insert( fact );
+ * ...
+ * entrypoint.update( factHandle, newFact );
+ * ...
+ * entrypoint.retract( factHandle );
+ * ...
+ * </pre>
+ *
+ */
public interface WorkingMemoryEntryPoint {
+ /**
+ * Inserts a new fact into this entry point
+ *
+ * @param object
+ * the fact to be inserted
+ *
+ * @return the fact handle created for the given fact
+ */
FactHandle insert(Object object);
+ /**
+ * Retracts the fact for which the given FactHandle was assigned.
+ *
+ * @param handle the handle whose fact is to be retracted.
+ */
void retract(FactHandle handle);
+ /**
+ * Updates the fact for which the given FactHandle was assigned with the new
+ * fact set as the second parameter in this method.
+ *
+ * @param handle the FactHandle for the fact to be updated.
+ *
+ * @param object the new value for the fact being updated.
+ */
void update(FactHandle handle,
Object object);
- WorkingMemoryEntryPoint getWorkingMemoryEntryPoint(String name);
}
More information about the jboss-svn-commits
mailing list