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);
}