Merge branch 'JAL-3878_ws-overhaul-3' into with_ws_overhaul-3

[jalview.git] / src / jalview / ws2 / actions / api / TaskEventListener.java

diff --git a/src/jalview/ws2/actions/api/TaskEventListener.java b/src/jalview/ws2/actions/api/TaskEventListener.java
new file mode 100644 (file)
index 0000000..94de9d0
--- /dev/null
+++ b/src/jalview/ws2/actions/api/TaskEventListener.java
@@ -0,0 +1,111 @@
+package jalview.ws2.actions.api;
+
+import java.util.List;
+
+import jalview.ws2.api.JobStatus;
+import jalview.ws2.api.WebServiceJobHandle;
+
+/**
+ * The listener interface for receiving relevant job progress and state change
+ * events on the task. The listener object is registered with the task on its
+ * creation in {@link ActionI#perform} method. An event is generated when the
+ * task is started, restarted, completed, fails with an exception or its global
+ * status changes. Additional, sub-job related, events are emitted when the
+ * sub-job status, log or error log changes.
+ * 
+ * @author mmwarowny
+ *
+ * @param <T>
+ */
+public interface TaskEventListener<T>
+{
+  /**
+   * Invoked when the task has been started. The {@code subJobs} parameter
+   * contains a complete list of sub-jobs for that run. Note that restartable
+   * tasks may invoke this method multiple times with different set of sub-jobs.
+   * 
+   * @param source
+   *          task this event originates from
+   * @param subJobs
+   *          list of sub-jobs for this run
+   */
+  void taskStarted(TaskI<T> source, List<? extends JobI> subJobs);
+
+  /**
+   * Invoked when the global task status has changed.
+   * 
+   * @param source
+   *          task this event originates from
+   * @param status
+   *          new task status
+   */
+  void taskStatusChanged(TaskI<T> source, JobStatus status);
+
+  /**
+   * Invoked when the task has completed. If the task completed with a result,
+   * that result is passed in the call argument, otherwise, a {@code null} value
+   * is given.
+   * 
+   * @param source
+   *          task this event originates from
+   * @param result
+   *          computation result or null if result not present
+   */
+  void taskCompleted(TaskI<T> source, T result);
+
+  /**
+   * Invoked when an unhandled exception has occurred during task execution.
+   * 
+   * @param source
+   *          task this event originates from
+   * @param e
+   *          exception
+   */
+  void taskException(TaskI<T> source, Exception e);
+
+  /**
+   * Invoked when the task had been restarted. This event is only applicable to
+   * restartable tasks and will precede each {@link #taskStarted} after the
+   * first one.
+   * 
+   * @param source
+   *          task this event originates from
+   */
+  void taskRestarted(TaskI<T> source);
+
+  /**
+   * Invoked when the status of a sub-job has changed.
+   * 
+   * @param source
+   *          task this event originates form
+   * @param job
+   *          sub-job that has been updated
+   * @param status
+   *          new job status
+   */
+  void subJobStatusChanged(TaskI<T> source, JobI job, JobStatus status);
+
+  /**
+   * Invoked when a log string of the sub-job has changed.
+   * 
+   * @param source
+   *          task this event originates form
+   * @param job
+   *          sub-job that has been updated
+   * @param log
+   *          new log string
+   */
+  void subJobLogChanged(TaskI<T> source, JobI job, String log);
+
+  /**
+   * Invoked when an error log string of the sub-job has changed.
+   * 
+   * @param source
+   *          task this event originates form
+   * @param job
+   *          sub-job that has been updated
+   * @param log
+   *          new log string
+   */
+  void subJobErrorLogChanged(TaskI<T> source, JobI job, String log);
+}