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

   1 package jalview.ws2.actions.api;
   2
   3 import java.util.List;
   4
   5 import jalview.bin.Console;
   6 import jalview.ws2.api.JobStatus;
   7 import jalview.ws2.api.WebServiceJobHandle;
   8
   9 /**
  10  * The listener interface for receiving relevant job progress and state change
  11  * events on the task. The listener object is registered with the task on its
  12  * creation in {@link ActionI#perform} method. An event is generated when the
  13  * task is started, restarted, completed, fails with an exception or its global
  14  * status changes. Additional, sub-job related, events are emitted when the
  15  * sub-job status, log or error log changes.
  16  *
  17  * @author mmwarowny
  18  *
  19  * @param <T>
  20  */
  21 public interface TaskEventListener<T>
  22 {
  23   /**
  24    * Invoked when the task has been started. The {@code subJobs} parameter
  25    * contains a complete list of sub-jobs for that run. Note that restartable
  26    * tasks may invoke this method multiple times with different set of 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<? extends JobI> 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} value
  48    * 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 to
  69    * restartable tasks and will precede each {@link #taskStarted} after the
  70    * 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, JobI 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, JobI 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, JobI job, String log);
 112
 113   @SuppressWarnings("rawtypes")
 114   static final TaskEventListener NULL_LISTENER = new TaskEventListener()
 115   {
 116     @Override
 117     public void taskStarted(TaskI source, List subJobs)
 118     {
 119       Console.info("task started with " + subJobs.size() + " jobs");
 120     }
 121
 122     @Override
 123     public void taskStatusChanged(TaskI source, JobStatus status)
 124     {
 125       Console.info("task status " + status);
 126     }
 127
 128     @Override
 129     public void taskCompleted(TaskI source, Object result)
 130     {
 131       Console.info("task completed");
 132     }
 133
 134     @Override
 135     public void taskException(TaskI source, Exception e)
 136     {
 137       Console.info("task failed", e);
 138     }
 139
 140     @Override
 141     public void taskRestarted(TaskI source)
 142     {
 143       Console.info("task restarted");
 144     }
 145
 146     @Override
 147     public void subJobStatusChanged(TaskI source, JobI job,
 148             JobStatus status)
 149     {
 150       Console.info("sub-job " + job.getInternalId() + " status " + status);
 151     }
 152
 153     @Override
 154     public void subJobLogChanged(TaskI source, JobI job, String log)
 155     {
 156     }
 157
 158     @Override
 159     public void subJobErrorLogChanged(TaskI source, JobI job, String log)
 160     {
 161     }
 162   };
 163
 164   @SuppressWarnings("unchecked")
 165   static <T> TaskEventListener<T> nullListener()
 166   {
 167     return (TaskEventListener<T>) NULL_LISTENER;
 168   }
 169 }