JAL-3878 Add methods to get and remove workers by their calc name.

[jalview.git] / src / jalview / api / AlignCalcManagerI2.java

diff --git a/src/jalview/api/AlignCalcManagerI2.java b/src/jalview/api/AlignCalcManagerI2.java
index c735c36..1e54e3e 100644 (file)
--- a/src/jalview/api/AlignCalcManagerI2.java
+++ b/src/jalview/api/AlignCalcManagerI2.java
@@ -4,23 +4,135 @@ import java.util.List;
 
 import jalview.datamodel.AlignmentAnnotation;
 
+/**
+ * An abstract manager which controls the execution of interactive jobs.
+ * There is always one instance of AlignCancManager per AlignmenViewport
+ * which runs the jobs, notifies observers and ensures no race conditions.
+ *
+ * @author mmwarowny
+ *
+ */
 public interface AlignCalcManagerI2
 {
+  /**
+   * Registers the worker with the manager and immediately schedules it
+   * for execution.
+   */
   void registerWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Returns the list of all registered workers or an empty list if
+   * there are none
+   */
   List<AlignCalcWorkerI> getWorkers();
+
+  /**
+   * Returns the list of all workers of a given class or an empty list
+   * if there are none. The classes are compared using
+   * {@ink Class#equals(Object)} rather than {@code instanceof}.
+   */
   List<AlignCalcWorkerI> getWorkersOfClass(Class<? extends AlignCalcWorkerI> cls);
+
+  /**
+   * Returns the list of all workers for the given name or an empty list
+   * if there are none.
+   */
+  List<AlignCalcWorkerI> getWorkersForName(String name);
+
+  /**
+   * Removes the worker from the scheduler. It does not cancel workers
+   * already scheduled for execution.
+   */
   void removeWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Removes all workers which are involved with the given annotation.
+   */
   void removeWorkerForAnnotation(AlignmentAnnotation annot);
+
+  /**
+   * Alias of removeWorkerForAnnotation
+   */
+  default void removeWorkersForAnnotation(AlignmentAnnotation annot) {
+    removeWorkerForAnnotation(annot);
+  }
+
+  /**
+   * Removes all workers with matching name.
+   */
+  void removeWorkersForName(String name);
+
+  /**
+   * Removes all workers of a given class. The classes are compared using
+   * {@link Class#equals(Object)}.
+   */
   void removeWorkersOfClass(Class<? extends AlignCalcWorkerI> cls);
+
+  /**
+   * Disables a worker so it won't be run during the following restarts.
+   */
   void disableWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Restores the previously disabled worker back to operation.
+   */
   void enableWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Checks whether the worker is disabled either due to failure or
+   * disabling it manually.
+   */
   boolean isDisabled(AlignCalcWorkerI worker);
+
+  /**
+   * Checks whether the given worker is currently running.
+   */
   boolean isWorking(AlignCalcWorkerI worker);
+
+  /**
+   * Checks whether the currently running worker (if any) is processing
+   * the given annotation.
+   */
   boolean isWorkingWithAnnotation(AlignmentAnnotation annot);
+
+  /**
+   * Checks whether this manager is running a worker.
+   */
   boolean isWorking();
+
+  /**
+   * Scheduler the worker for one-time execution. The worker does not need
+   * to be registered with this manager and will be scheduler regardless
+   * of being disabled. If the worker has already been scheduled, the
+   * previous one will be cancelled.
+   */
   void startWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Schedules all registered and not-disabled workers for next execution.
+   */
   void restartWorkers();
+
+  /**
+   * Cancels the execution of the worker. Note, if the worker is already
+   * running, this method may, but doesn't have to, interrupt it in
+   * the middle of the work.
+   */
   void cancelWorker(AlignCalcWorkerI worker);
+
+  /**
+   * Connect the listener of the worker state changes.
+   */
   void addAlignCalcListener(AlignCalcListener listener);
+
+  /**
+   * Remove previously registered worker listener.
+   */
   void removeAlignCalcListener(AlignCalcListener listener);
+
+  /**
+   * Stops the manager from running new jobs and cleans-up all
+   * resources such as threads and thread pools.
+   */
+  void shutdown();
 }