src/jalview/ws2/PollableTaskI.java

   1 package jalview.ws2;
   2
   3 /**
   4  * The {@code PollableTaskI} interface should be implemented by classes
   5  * representing a background task that must be polled repeatedly to check for
   6  * completion. Those are typically jobs that run on a remote host and need to be
   7  * periodically checked for status updates.
   8  *
   9  * The life-cycle of a task consist of calling {@link #start} method once to
  10  * start the process, followed by repeated calls to {@link #poll} that should
  11  * check for execution status and finally {@link #done} method that finalizes
  12  * the process.
  13  *
  14  * The instances can be started with {@link PollingTaskExecutor} which manages
  15  * start up, polling and finalization of the task using a thread executor.
  16  *
  17  * @author mmwarowny
  18  *
  19  */
  20 public interface PollableTaskI
  21 {
  22   /**
  23    * Called by the executor once and the beginning to start the task. May throw
  24    * any exception, in such case the task will be interrupted.
  25    *
  26    * @throws Exception
  27    */
  28   void start() throws Exception;
  29
  30   /**
  31    * Called repeatedly by the executor to check for task completion. The
  32    * implementation should check the remote host for job status updates and
  33    * return true when the task is finished. If any exception is thrown, the task
  34    * is interrupted.
  35    *
  36    * @return whether the task is done
  37    * @throws Exception
  38    */
  39   boolean poll() throws Exception;
  40
  41   /**
  42    * @return whether the task is done
  43    */
  44   boolean isDone();
  45
  46   /**
  47    * Called once the task is done running ({@link #poll} returned true) to
  48    * finalize the task and collect the results.
  49    */
  50   void done();
  51 }