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

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

diff --git a/src/jalview/ws2/PollingTaskExecutor.java b/src/jalview/ws2/PollingTaskExecutor.java
index 3e04c17..c003e49 100644 (file)
--- a/src/jalview/ws2/PollingTaskExecutor.java
+++ b/src/jalview/ws2/PollingTaskExecutor.java
@@ -8,11 +8,31 @@ import java.util.concurrent.TimeUnit;
 
 import jalview.bin.Cache;
 
+/**
+ * An object that executes submitted {@link PollableTaskI} tasks using
+ * {@link SchedulekExecutorservice}. The task is first started using its
+ * {@link PollableTaskI#start} method and then repeatedly polled every second
+ * with {@link PollableTaskI#poll}.
+ * 
+ * The {@link PollingTaskExecutor} automates the process of running tasks and
+ * provides convenient interface to listen to events associated with task
+ * execution.
+ * 
+ * @author mmwarowny
+ *
+ */
 public class PollingTaskExecutor
 {
   private ScheduledExecutorService executor = Executors
-          .newSingleThreadScheduledExecutor();
-
+      .newSingleThreadScheduledExecutor();
+
+  /**
+   * Submit the task for execution. Calls task's {@code start} method and, if
+   * started successfully, schedules next poll after one second.
+   * 
+   * @param task
+   *          task to submit
+   */
   public void submit(final PollableTaskI task)
   {
     executor.submit(() -> {
@@ -30,6 +50,14 @@ public class PollingTaskExecutor
     });
   }
 
+  /**
+   * Poll the task by calling it's {@code poll} method. If not finished, the
+   * next poll is scheduled to happen after one second, otherwise task's
+   * {@code done} method is called immediately.
+   * 
+   * @param task
+   *          task to poll
+   */
   private void poll(PollableTaskI task)
   {
     boolean done;
@@ -55,11 +83,21 @@ public class PollingTaskExecutor
 
   private WebServiceThreadSupport wsThreadSupport = new WebServiceThreadSupport();
 
+  /**
+   * Add listener of the task related events.
+   * 
+   * @param listener
+   *          listener to add
+   */
   public void addThreadListener(PollableTaskListenerI listener)
   {
     wsThreadSupport.addListener(listener);
   }
 
+  /**
+   * @param listener
+   *          listener to be removed
+   */
   public void removeThreadListener(PollableTaskListenerI listener)
   {
     wsThreadSupport.removeListener(listener);