JAL-3878 Add javadocs to created classes and reformat code.

[jalview.git] / src / jalview / ws2 / PollableTaskI.java

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