src/jalview/ws2/actions/api/TaskEventListener.java

   1 package jalview.ws2.actions.api;
   2
   3 import java.util.List;
   4
   5 import jalview.ws2.api.JobStatus;
   6 import jalview.ws2.api.WebServiceJobHandle;
   7
   8 /**
   9  * The listener interface for receiving relevant job progress and state change
  10  * events on the task. The listener object is registered with the task on its
  11  * creation in {@link ActionI#perform} method. An event is generated when the
  12  * task is started, restarted, completed, fails with an exception or its global
  13  * status changes. Additional, sub-job related, events are emitted when the
  14  * sub-job status, log or error log changes.
  15  *
  16  * @author mmwarowny
  17  *
  18  * @param <T>
  19  */
  20 public interface TaskEventListener<T>
  21 {
  22   /**
  23    * Invoked when the task has been started. The {@code subJobs} parameter
  24    * contains a complete list of sub-jobs for that run. Note that restartable
  25    * tasks may invoke this method multiple times with different set of sub-jobs.
  26    *
  27    * @param source
  28    *          task this event originates from
  29    * @param subJobs
  30    *          list of sub-jobs for this run
  31    */
  32   void taskStarted(TaskI<T> source, List<? extends JobI> subJobs);
  33
  34   /**
  35    * Invoked when the global task status has changed.
  36    *
  37    * @param source
  38    *          task this event originates from
  39    * @param status
  40    *          new task status
  41    */
  42   void taskStatusChanged(TaskI<T> source, JobStatus status);
  43
  44   /**
  45    * Invoked when the task has completed. If the task completed with a result,
  46    * that result is passed in the call argument, otherwise, a {@code null} value
  47    * is given.
  48    *
  49    * @param source
  50    *          task this event originates from
  51    * @param result
  52    *          computation result or null if result not present
  53    */
  54   void taskCompleted(TaskI<T> source, T result);
  55
  56   /**
  57    * Invoked when an unhandled exception has occurred during task execution.
  58    *
  59    * @param source
  60    *          task this event originates from
  61    * @param e
  62    *          exception
  63    */
  64   void taskException(TaskI<T> source, Exception e);
  65
  66   /**
  67    * Invoked when the task had been restarted. This event is only applicable to
  68    * restartable tasks and will precede each {@link #taskStarted} after the
  69    * first one.
  70    *
  71    * @param source
  72    *          task this event originates from
  73    */
  74   void taskRestarted(TaskI<T> source);
  75
  76   /**
  77    * Invoked when the status of a sub-job has changed.
  78    *
  79    * @param source
  80    *          task this event originates form
  81    * @param job
  82    *          sub-job that has been updated
  83    * @param status
  84    *          new job status
  85    */
  86   void subJobStatusChanged(TaskI<T> source, JobI job, JobStatus status);
  87
  88   /**
  89    * Invoked when a log string of the sub-job has changed.
  90    *
  91    * @param source
  92    *          task this event originates form
  93    * @param job
  94    *          sub-job that has been updated
  95    * @param log
  96    *          new log string
  97    */
  98   void subJobLogChanged(TaskI<T> source, JobI job, String log);
  99
 100   /**
 101    * Invoked when an error log string of the sub-job has changed.
 102    *
 103    * @param source
 104    *          task this event originates form
 105    * @param job
 106    *          sub-job that has been updated
 107    * @param log
 108    *          new log string
 109    */
 110   void subJobErrorLogChanged(TaskI<T> source, JobI job, String log);
 111 }