package jalview.ws2;

/**
 * The {@code PollableTaskI} interface should be implemented by classes
 * representing a background task that must be polled repeatedly to check for
 * completion. Those are typically jobs that run on a remote host and need to be
 * periodically checked for status updates.
 * 
 * The life-cycle of a task consist of calling {@link #start} method once to
 * start the process, followed by repeated calls to {@link #poll} that should
 * check for execution status and finally {@link #done} method that finalizes
 * the process.
 * 
 * The instances can be started with {@link PollingTaskExecutor} which manages
 * start up, polling and finalization of the task using a thread executor.
 * 
 * @author mmwarowny
 *
 */
public interface PollableTaskI
{
  /**
   * Called by the executor once and the beginning to start the task. May throw
   * any exception, in such case the task will be interrupted.
   * 
   * @throws Exception
   */
  void start() throws Exception;

  /**
   * Called repeatedly by the executor to check for task completion. The
   * implementation should check the remote host for job status updates and
   * return true when the task is finished. If any exception is thrown, the task
   * is interrupted.
   * 
   * @return whether the task is done
   * @throws Exception
   */
  boolean poll() throws Exception;

  /**
   * @return whether the task is done
   */
  boolean isDone();

  /**
   * Called once the task is done running ({@link #poll} returned true) to
   * finalize the task and collect the results.
   */
  void done();
}