X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fws2%2FPollableTaskI.java;fp=src%2Fjalview%2Fws2%2FPollableTaskI.java;h=d097974f5018843e928e92ad4f305e203caa31b5;hb=2bbba7f7426314bfd6a1f206861542244b5f511a;hp=88c7371d74b41a75524b1147025a400f12aab605;hpb=158e0595615ae4bfb13554f41f03b570642f6bb2;p=jalview.git

diff --git a/src/jalview/ws2/PollableTaskI.java b/src/jalview/ws2/PollableTaskI.java
index 88c7371..d097974 100644
--- a/src/jalview/ws2/PollableTaskI.java
+++ b/src/jalview/ws2/PollableTaskI.java
@@ -1,12 +1,51 @@
 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();
 }