[jboss-svn-commits] JBL Code SVN: r12943 - labs/jbossrules/trunk/drools-core/src/main/java/org/drools.

[jboss-svn-commits at lists.jboss.org]

Author: michael.neale at jboss.com
Date: 2007-06-28 20:35:39 -0400 (Thu, 28 Jun 2007)
New Revision: 12943

Modified:
   labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatefulSession.java
   labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatelessSession.java
Log:
added some missing javadocs

Modified: labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatefulSession.java
===================================================================
--- labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatefulSession.java	2007-06-28 23:59:46 UTC (rev 12942)
+++ labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatefulSession.java	2007-06-29 00:35:39 UTC (rev 12943)
@@ -5,6 +5,12 @@
 import org.drools.concurrent.Future;
 import org.drools.spi.AgendaFilter;
 
+/**
+ * A stateful session represents a working memory which keeps state 
+ * between invocations (accumulating facts/knowledge).
+ * 
+ * Caution should be used when using the async methods (take not of the javadocs for specific methods). 
+ */
 public interface StatefulSession extends WorkingMemory {
     
     /**
@@ -12,15 +18,51 @@
      * 
      */
     void dispose();    
-    
+
+    /**
+     * Insert/Assert an object asynchronously.
+     * (return immediately, even while the insertion is taking effect).
+     * The returned Future object can be queried to check on the status of the task.
+     * You should only use the async methods if you are sure you require a background 
+     * insertion task to take effect (a new thread may be created). 
+     * If you are not sure, then you probably don't need to use it !
+     */
     Future asyncInsert(Object object);    
     Future asyncRetract(FactHandle factHandle);   
     Future asyncUpdate(FactHandle factHandle, Object object);
 
+    /**
+     * Insert/Assert an array of objects..
+     * (return immediately, even while the insertion is taking effect).
+     * The returned Future object can be queried to check on the status of the task.
+     * You should only use the async methods if you are sure you require a background 
+     * insertion task to take effect (a new thread may be created). 
+     * If you are not sure, then you probably don't need to use it !
+     */    
     Future asyncInsert(Object[] list);
+    
+    /**
+     * Insert/Assert a list of objects..
+     * (return immediately, even while the insertion is taking effect).
+     * The returned Future object can be queried to check on the status of the task.
+     * You should only use the async methods if you are sure you require a background 
+     * insertion task to take effect (a new thread may be created). 
+     * If you are not sure, then you probably don't need to use it !
+     */        
     Future asyncInsert(List list);
     
+    /**
+     * This will initiate the firing phase (in the background). 
+     * And return immediately. The returned Future object can be queried
+     * to check on the status of the task.
+     */
     Future asyncFireAllRules();
+    
+    /**
+     * This will initiate the firing phase (in the background). 
+     * And return immediately. The returned Future object can be queried
+     * to check on the status of the task.
+     */    
     Future asyncFireAllRules(AgendaFilter agendaFilter); 
 
 }

Modified: labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatelessSession.java
===================================================================
--- labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatelessSession.java	2007-06-28 23:59:46 UTC (rev 12942)
+++ labs/jbossrules/trunk/drools-core/src/main/java/org/drools/StatelessSession.java	2007-06-29 00:35:39 UTC (rev 12943)
@@ -6,6 +6,16 @@
 import org.drools.spi.AgendaFilter;
 import org.drools.spi.GlobalResolver;
 
+/**
+ * This represents a working memory session where state is not kept between
+ * invocations.
+ * This is typically used for "decision services" where the rules are
+ * provided all the data in one hit, and a conclusion reached by the engine.
+ * (there is no accumulation of facts/knowledge - each invocation is on a fresh session).
+ * 
+ * Care should be used when using the async versions of the methods, consult the javadoc for 
+ * the specific information.
+ */
 public interface StatelessSession {
     /**
      * Returns all event listeners.
@@ -41,22 +51,59 @@
     
     void setGlobal(String identifer, Object value);        
     
-    
+    /**
+     * Insert a single fact, an fire the rules, returning when finished.
+     */
     void execute(Object object);
-   
+
+    /**
+     * Insert an array of facts, an fire the rules, returning when finished.
+     * This will assert the list of facts as SEPARATE facts to the engine
+     * (NOT an array).
+     */    
     void execute(Object[] list);
-    
+
+    /**
+     * Insert a List of facts, an fire the rules, returning when finished.
+     * This will assert the list of facts as SEPARATE facts to the engine
+     * (NOT as a List).
+     */        
     void execute(List list);    
     
+    /**
+     * This will assert the object in the background. This is
+     * "send and forget" execution.
+     */
     void asyncExecute(Object object);
-    
+
+    /**
+     * This will assert the object array (as SEPARATE facts) in the background. This is
+     * "send and forget" execution.
+     */
     void asyncExecute(Object[] list);
-    
+
+    /**
+     * This will assert the object List (as SEPARATE facts) in the background. This is
+     * "send and forget" execution.
+     */    
     void asyncExecute(List list);      
     
+    
+    /**
+     * Similar to the normal execute method, but this will return
+     * "results". 
+     */
     StatelessSessionResult executeWithResults(Object object);
-   
+
+    /**
+     * Similar to the normal execute method, but this will return
+     * "results". 
+     */    
     StatelessSessionResult executeWithResults(Object[] list);
-    
+
+    /**
+     * Similar to the normal execute method, but this will return
+     * "results". 
+     */   
     StatelessSessionResult executeWithResults(List list);
 }