Commits

Michael Ludwig committed 5a4f1b3

Add documentation to SimpleTask, and improve documentation of Result and Task.

Comments (0)

Files changed (3)

src/main/java/com/lhkbob/entreri/task/Result.java

 /**
  * <p>
  * Result represents a computed result, preferably that of a bulk computation,
- * performed by a Controller. Results allow Controllers to easily pass data to
- * other controllers that might be interested in their computations.
+ * performed by a Task. Results allow Taskss to easily pass data to other tasks
+ * in the same job that might be interested in their computations.
  * </p>
  * <p>
- * Controllers that wish to expose results define classes that implement Result
- * and expose the actual result data. During processing of a controller, result
- * instances are created and supplied to all controllers by calling
- * {@link Scheduler#report(Result)}
+ * Tasks that wish to expose results define classes that extend Result and
+ * provide the actual result data. During processing of a task, result instances
+ * are created and supplied to all future tasks by calling
+ * {@link Job#report(Result)}
  * </p>
  * <p>
- * To receive computed results, Controllers override their
- * {@link Task#report(Result)} and check incoming results for the desired type
- * of result. Every controller is notified of all results, they are responsible
- * for ignoring results they are not interested in.
+ * To receive computed results, Tasks define
+ * <code>public void report(T extends Result)</code> methods that are invoked
+ * through reflection by the job when a compatible result is reported.
  * </p>
  * 
  * @author Michael Ludwig
      * <p>
      * Return true if this result is a "singleton" result. A singleton result is
      * a type of result that is can only be reported once per execution of a
-     * job. The ControllerManager verifies that singleton results are supplied
-     * at most once. Most results should return false. The returned value should
-     * be the same for every instance of a type, it should not depend on the
-     * state of the instance.
+     * job. The job verifies that singleton results are supplied at most once
+     * per job execution. Most results should return false. The returned value
+     * should be the same for every instance of a type, it should not depend on
+     * the state of the instance.
      * </p>
      * <p>
      * Singleton results should only be used when the computation of the result
      * <p>
      * The default implementation returns false. Subtypes are free to override
      * it, but it must return the same value for all instances of a given type.
+     * </p>
      * 
      * @return True if this result should only be supplied at most once during
      *         each frame

src/main/java/com/lhkbob/entreri/task/SimpleTask.java

 import com.lhkbob.entreri.ComponentIterator;
 import com.lhkbob.entreri.EntitySystem;
 
+/**
+ * <p>
+ * SimpleTask extends Task adds logic to simplify the creation of tasks that
+ * perform the same operations on each entity that matches a specific component
+ * configuration. Subclasses of SimpleTask should define a single method named
+ * 'processEntity' that takes as its only parameters, any number of
+ * ComponentData instances of specific types. An example might be:
+ * 
+ * <pre>
+ * public class ExampleTask extends SimpleTask {
+ *     // c1 and c2 are required types
+ *     // c3 is an optional component type
+ *     protected void processEntities(TypeA c1, TypeB c2, @Optional TypeC c3) {
+ *         // perform operations on c1 and c2
+ *         if (c3 != null) {
+ *             // perform additional operations on c3
+ *         }
+ *     }
+ * 
+ *     public Task process(EntitySystem system, Job job) {
+ *         // this will invoke processEntities() for each entity in the system
+ *         // that has a TypeA and TypeB component. If the entity also has
+ *         // a TypeC component, it is passed in too, otherwise it's null
+ *         processEntities(system);
+ *         return null;
+ *     }
+ * }
+ * </pre>
+ * <p>
+ * In the task's {@link #process(EntitySystem, Job)} method, it can then invoke
+ * {@link #processEntities(EntitySystem)} to perform the automated iteration
+ * over matching entities within the system. SimpleTask will call the identified
+ * 'processEntity' method for each matched entity.
+ * 
+ * @author Michael Ludwig
+ * 
+ */
 public abstract class SimpleTask implements Task {
     @Target(ElementType.PARAMETER)
     @Retention(RetentionPolicy.RUNTIME)
     // filled with instances after first call to processEntities
     private final ComponentData<?>[] componentDatas;
 
-    // "final" after the first call to processEntities()
+    // "final" after the first call to processEntities() or until the system changes
     private ComponentIterator iterator;
+    private EntitySystem lastSystem;
 
     public SimpleTask() {
         Method processMethod = null;
         }
     }
 
+    /**
+     * Process all entities that fit the component profile mandated by the
+     * defined 'processEntity()' method in the subclass.
+     * 
+     * @param system The system to process
+     */
     @SuppressWarnings({"unchecked", "rawtypes"})
     protected void processEntities(EntitySystem system) {
-        if (iterator == null) {
+        if (iterator == null || lastSystem != system) {
             iterator = new ComponentIterator(system);
             for (int i = 0; i < optional.length; i++) {
                 ComponentData<?> data = system.createDataInstance((Class) processMethod.getParameterTypes()[i]);
                 }
                 componentDatas[i] = data;
             }
+
+            lastSystem = system;
         }
 
         try {

src/main/java/com/lhkbob/entreri/task/Task.java

  * <p>
  * A task can communicate with the remaining tasks of a job by
  * {@link Job#report(Result) reporting} results. The results are only reported
- * to tasks within the owning job, and are executed after the current task. Thus
- * tasks that have already completed their processing will not receive new
+ * to tasks within the owning job, and that are executed after the current task.
+ * Thus tasks that have already completed their processing will not receive new
  * results.
  * <p>
  * A task receives results by defining any number of methods with the signature
  * <code>public void report(T extends Result)</code>. When a result is reported
  * to the job, it will invoke using reflection any <code>report()</code> method
- * that takes a result of compatible type.
+ * that takes a result of the compatible type.
  * <p>
  * Task instances should only ever be used with a single job and entity system.
  * If the task needs to be performed in multiple jobs or systems, new instances