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.WebServiceJob;
   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
  26    * sub-jobs.
  27    *
  28    * @param source
  29    *    task this event originates from
  30    * @param subJobs
  31    *    list of sub-jobs for this run
  32    */
  33   void taskStarted(TaskI<T> source, List<WebServiceJob> subJobs);
  34
  35   /**
  36    * Invoked when the global task status has changed.
  37    *
  38    * @param source
  39    *    task this event originates from
  40    * @param status
  41    *    new task status
  42    */
  43   void taskStatusChanged(TaskI<T> source, JobStatus status);
  44
  45   /**
  46    * Invoked when the task has completed. If the task completed with a result,
  47    * that result is passed in the call argument, otherwise, a {@code null}
  48    * value is given.
  49    *
  50    * @param source
  51    *    task this event originates from
  52    * @param result
  53    *    computation result or null if result not present
  54    */
  55   void taskCompleted(TaskI<T> source, T result);
  56
  57   /**
  58    * Invoked when an unhandled exception has occurred during task execution.
  59    *
  60    * @param source
  61    *    task this event originates from
  62    * @param e
  63    *    exception
  64    */
  65   void taskException(TaskI<T> source, Exception e);
  66
  67   /**
  68    * Invoked when the task had been restarted. This event is only applicable
  69    * to restartable tasks and will precede each {@link #taskStarted} after
  70    * the first one.
  71    *
  72    * @param source
  73    *    task this event originates from
  74    */
  75   void taskRestarted(TaskI<T> source);
  76
  77   /**
  78    * Invoked when the status of a sub-job has changed.
  79    *
  80    * @param source
  81    *    task this event originates form
  82    * @param job
  83    *    sub-job that has been updated
  84    * @param status
  85    *    new job status
  86    */
  87   void subJobStatusChanged(TaskI<T> source, WebServiceJob job, JobStatus status);
  88
  89   /**
  90    * Invoked when a log string of the sub-job has changed.
  91    *
  92    * @param source
  93    *    task this event originates form
  94    * @param job
  95    *    sub-job that has been updated
  96    * @param log
  97    *    new log string
  98    */
  99   void subJobLogChanged(TaskI<T> source, WebServiceJob job, String log);
 100
 101   /**
 102    * Invoked when an error log string of the sub-job has changed.
 103    *
 104    * @param source
 105    *    task this event originates form
 106    * @param job
 107    *    sub-job that has been updated
 108    * @param log
 109    *    new log string
 110    */
 111   void subJobErrorLogChanged(TaskI<T> source, WebServiceJob job, String log);
 112 }