added documentation

mp2079 [2003-05-14 15:42:20]
added documentation
Filename
littlejil/ExceptionHandlerPlugin.java
littlejil/ExecutableTask.java
littlejil/LittleJILExpanderPlugin.java
littlejil/TaskAllocatorPlugin.java
littlejil/TaskExecutorWorkletPlugin.java
littlejil/TaskExpanderPlugin.java
littlejil/TaskMonitorGUI.java
diff --git a/littlejil/ExceptionHandlerPlugin.java b/littlejil/ExceptionHandlerPlugin.java
index e550ef1..5119d92 100644
--- a/littlejil/ExceptionHandlerPlugin.java
+++ b/littlejil/ExceptionHandlerPlugin.java
@@ -16,19 +16,33 @@ import laser.littlejil.HandlerBinding;
 import laser.littlejil.Step;

 /**
- * This class handles exceptions thrown when executing a task.
+ * This plugin handles exceptions that occur in the LittleJIL workflow.
+ * Exceptions are thrown by plugins by publishing
+ * <code>LittleJILException</code> objects. In general exceptions are thrown
+ * when a task fails, or when a resource or execution agent asset cannot be
+ * found.
  *
- * Exceptions are thrown by publishing a LittleJILException object, to which this plugin subscribes.
- * When an exception is received:
- *  - if it was thrown by a child task, any other child tasks that depended on that one are removed
- *      NOTE that this means that if a task has parallel sequencing, then the other substeps will still
- *      run (i.e., will not be removed). This seems to follow the LittleJIL language report v1.0
- *  - the exception handler is retrieved. at the moment only the first one is considered
- *  - the rest corresponds to the behavior of the exception handler (restarting, continuing, completing, rethrowing)
+ * There are four different types of exception handlers in LittleJIL:
+ * <em>restart</em>, <em>continue</em>, <em>complete</em>, and <em>rethrow</em>
+ * (see the <a class="ref" href="#ref">LittleJIL reference</a> for details).
+ * This plugin handles all four types. For restart, continue, and complete, it
+ * works in general by aborting the expansion where the failed task is (thus
+ * preventing more sibling tasks from running), and sending an
+ * <code>ExceptionHandlerRequest</code> to the
+ * <code>LittleJILExpanderPlugin</code> for the task to be republished as
+ * necessary. If a task fails and an exception handler cannot be found, the
+ * exception is re-thrown to the parent task.
  *
+ * Exceptions are thrown by publishing a LittleJILException object, to which
+ * this plugin subscribes. When an exception is received: if it was thrown by a
+ * child task, any other child tasks that depended on that one are removed NOTE
+ * that this means that if a task has parallel sequencing, then the other
+ * substeps will still run (i.e., will not be removed). This seems to follow the
+ * LittleJIL language report v1.0 the exception handler is retrieved. at the
+ * moment only the first one is considered the rest corresponds to the behavior
+ * of the exception handler (restarting, continuing, completing, rethrowing)
  *
- *
- * Implementing the PrivilegedClaimant interface allows this plugin to remove expansion that were
+ * Note: Implementing the PrivilegedClaimant interface allows this plugin to remove expansion that were
  * posted by other plugins
  *
  * @author matias
diff --git a/littlejil/ExecutableTask.java b/littlejil/ExecutableTask.java
index d0522cc..4f1c5a6 100644
--- a/littlejil/ExecutableTask.java
+++ b/littlejil/ExecutableTask.java
@@ -4,7 +4,7 @@ import java.util.Hashtable;

 /**
  * This interface is implemented by classes that can be used to execute Little-JIL tasks via
- * the TaskExecutorInternalPlugin.
+ * the TaskExecutorClassPlugin.
  *
  * @author matias@cs.columbia.edu
  */
diff --git a/littlejil/LittleJILExpanderPlugin.java b/littlejil/LittleJILExpanderPlugin.java
index f34fcf2..a7ff3ef 100644
--- a/littlejil/LittleJILExpanderPlugin.java
+++ b/littlejil/LittleJILExpanderPlugin.java
@@ -12,17 +12,22 @@ import org.cougaar.planning.ldm.plan.*;
 import org.cougaar.util.UnaryPredicate;

 /**
- * This plugin parses a LittleJIL diagram and publishes the root task to be expanded
- * by the ExpanderPlugin.
- *
- * It subscribes to Little-JIL diagrams, and requests from other plugins (like TaskExpander
- * and ExceptionHandler) when tasks need to be re-posted, etc.
+ * The <code>LittleJILExpanderPlugin</code> subscribes to LittleJIL
+ * <code>Diagram</code> objects. For each diagram, it gets the root task and
+ * calls the internal <code>makeTask</code> method. <code>makeTask</code>
+ * creates a Cougaar Task object for the given LittleJIL step, and then
+ * recursively calls <code>makeTask</code> for each of the substeps of the
+ * current step. As it calls <code>makeTask</code> it sets the constraints
+ * appropriately if the step is of sequential kind. It also handles step
+ * cardinality, and has special cases for <em>choice</em> tasks and for
+ * restarting tasks with <em>continue</em> exception handlers. For tasks with
+ * pre- or post-requisites, the method <code>makeTaskWithRequisites</code> is
+ * called, which creates a "parent" task with the requisites and the actual
+ * tasks as subtasks.
  *
  * It also keeps a table that maps between Tasks and Steps in the blackboard.
- *
  * @author matias
  */
-
 public class LittleJILExpanderPlugin extends ComponentPlugin {

     private static final Logger logger = Logger.getLogger(LittleJILExpanderPlugin.class);
diff --git a/littlejil/TaskAllocatorPlugin.java b/littlejil/TaskAllocatorPlugin.java
index 989070e..9d2c96f 100644
--- a/littlejil/TaskAllocatorPlugin.java
+++ b/littlejil/TaskAllocatorPlugin.java
@@ -14,8 +14,11 @@ import org.cougaar.util.UnaryPredicate;
 import psl.workflakes.littlejil.assets.*;

 /**
- * This class should get tasks posted on a blackboard and allocate them according to
- * the given workflow
+ * This plugin subscribes to leaf tasks and for each one it allocates an
+ * <code>ExecAgentAsset</code> to it and publishes the allocation. Its
+ * <code>findExecAgent</code> method can be overriden by a subclass to provide
+ * for better finding. At the moment it just matches the task name against the
+ * ExecAgent's "capabilities" property.
  * @author matias
  */

@@ -90,7 +93,7 @@ public class TaskAllocatorPlugin extends ComponentPlugin {
             executorPG.setCapabilities("any");

             NewClassPG classPG = (NewClassPG) factory.createPropertyGroup("ClassPG");
-            //classPG.setClassName("psl.workflakes.littlejil.TaskExecutorInternalPlugin$DummyExecutableTask");
+            //classPG.setClassName("psl.workflakes.littlejil.TaskExecutorClassPlugin$DummyExecutableTask");
             classPG.setClassName("psl.ai2tv.workflow.AI2TVPlugin$DummyExecutableTask");
             asset.setExecutorPG(executorPG);
             asset.setClassPG(classPG);
@@ -127,6 +130,9 @@ public class TaskAllocatorPlugin extends ComponentPlugin {
             } catch (PluginException e) {
                 logger.warn("Could not find asset for task " + task.getVerb() + ": " + e);
                 logger.warn("Not publishing task");
+
+                // publish littleJil exception
+                blackboard.publishAdd(new LittleJILException(task, "ExecAgentAssetNotFound"));
             }


diff --git a/littlejil/TaskExecutorWorkletPlugin.java b/littlejil/TaskExecutorWorkletPlugin.java
index 9ff17ed..46e9cdd 100644
--- a/littlejil/TaskExecutorWorkletPlugin.java
+++ b/littlejil/TaskExecutorWorkletPlugin.java
@@ -14,9 +14,18 @@ import java.io.Serializable;
 import java.util.Hashtable;

 /**
- * This plugin uses a Worklet to execute task.
  *
- * NOTE: currently, all tasks are executed using a TaskMonitor Worklet Junction.
+ * This plugin extends the <code>AbstractTaskExecutorPlugin</code> and
+ * subscribes to <code>ExecWorkletAssetAsset</code>s. It implements the
+ * <code>executeTask</code> method so that a <a class="ref"
+ * href="ref">Worklet</a> is launched to execute the given task.
+ *
+ * At the moment this plugin is used mostly for testing purposes. For example,
+ * it always uses a <code>TaskMonitorJunction</code> worklet junction that is
+ * intended to go to a running instance of a <code>TaskMonitor</code> or
+ * <code>TaskMonitorGUI</code>. In reality it should use the junction that is
+ * specified as part of the <code>ExecWorkletAssetAsset</code> for the task.
+ *
  *
  * The following system properties should be set:
  *     psl.workflakes.littlejil.useWorklets: true if worklets should be used
diff --git a/littlejil/TaskExpanderPlugin.java b/littlejil/TaskExpanderPlugin.java
index f0e955f..8627813 100644
--- a/littlejil/TaskExpanderPlugin.java
+++ b/littlejil/TaskExpanderPlugin.java
@@ -14,9 +14,20 @@ import laser.littlejil.ParameterBinding;
 import laser.littlejil.ParameterDeclaration;

 /**
- * This class gets tasks posted on a blackboard and expand their workflows as necessary.
- *
+ * This plugin is in charge of processing the Task expansions that the
+ * <code>LittleJILExpanderPlugin</code> posts. It subscribes to expandable (i.e.
+ * non-leaf) tasks. When executed, it does two main things: for all the
+ * expansions, it checks if a constraint has been satisfied (for example, after
+ * the first of a sequential set of leaf tasks has completed), and if so it
+ * posts the next available leaf task for that expansion. It also checks to see
+ * if expansions that have not been started yet have any more constraints
+ * imposed on them (for example, a parent task that comes sequentially after
+ * another parent task). If there are no more constraints, it publishes the
+ * child tasks of the expansion as necessary.
  *
+ *  The <code>TaskExpanderPlugin</code> also sets the in and out parameters of
+ *  leaf tasks as necessary, and provides methods for listeners to subscribe to
+ *  events such as "task started" or "task completed".
  *
  * @author matias
  */
diff --git a/littlejil/TaskMonitorGUI.java b/littlejil/TaskMonitorGUI.java
index 7624a42..12a299b 100644
--- a/littlejil/TaskMonitorGUI.java
+++ b/littlejil/TaskMonitorGUI.java
@@ -15,8 +15,11 @@ import java.awt.*;
 import java.util.Vector;

 /**
+ * This GUI can be used to test the TaskExecutorWorkletPlugin. As it receives worklets for each task,
+ * the user can choose whether the task succeeds or fails. The worklet is then shipped back to the Executor plugin
+ * to report on the outcome.
  *
- * @author  Matias
+ * @author  matias
  */
 public class TaskMonitorGUI extends javax.swing.JFrame implements TaskMonitor {