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   default 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   default 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   default 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   default void taskException(TaskI<T> source, Exception e) {};
  66
  67   /**
  68    * Invoked when the status of a sub-job has changed.
  69    *
  70    * @param source
  71    *          task this event originates form
  72    * @param job
  73    *          sub-job that has been updated
  74    * @param status
  75    *          new job status
  76    */
  77   default void subJobStatusChanged(TaskI<T> source, JobI job, JobStatus status) {};
  78
  79   /**
  80    * Invoked when a log string of the sub-job has changed.
  81    *
  82    * @param source
  83    *          task this event originates form
  84    * @param job
  85    *          sub-job that has been updated
  86    * @param log
  87    *          new log string
  88    */
  89   default void subJobLogChanged(TaskI<T> source, JobI job, String log) {};
  90
  91   /**
  92    * Invoked when an error log string of the sub-job has changed.
  93    *
  94    * @param source
  95    *          task this event originates form
  96    * @param job
  97    *          sub-job that has been updated
  98    * @param log
  99    *          new log string
 100    */
 101   default void subJobErrorLogChanged(TaskI<T> source, JobI job, String log) {};
 102
 103   @SuppressWarnings("rawtypes")
 104   static final TaskEventListener NULL_LISTENER = new TaskEventListener()
 105   {
 106     @Override
 107     public void taskStarted(TaskI source, List subJobs)
 108     {
 109       Console.info("task started with " + subJobs.size() + " jobs");
 110     }
 111
 112     @Override
 113     public void taskStatusChanged(TaskI source, JobStatus status)
 114     {
 115       Console.info("task status " + status);
 116     }
 117
 118     @Override
 119     public void taskCompleted(TaskI source, Object result)
 120     {
 121       Console.info("task completed");
 122     }
 123
 124     @Override
 125     public void taskException(TaskI source, Exception e)
 126     {
 127       Console.info("task failed", e);
 128     }
 129
 130     @Override
 131     public void subJobStatusChanged(TaskI source, JobI job,
 132             JobStatus status)
 133     {
 134       Console.info("sub-job " + job.getInternalId() + " status " + status);
 135     }
 136
 137     @Override
 138     public void subJobLogChanged(TaskI source, JobI job, String log)
 139     {
 140     }
 141
 142     @Override
 143     public void subJobErrorLogChanged(TaskI source, JobI job, String log)
 144     {
 145     }
 146   };
 147
 148   @SuppressWarnings("unchecked")
 149   static <T> TaskEventListener<T> nullListener()
 150   {
 151     return (TaskEventListener<T>) NULL_LISTENER;
 152   }
 153 }