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

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

diff --git a/src/jalview/ws2/WebServiceWorkerI.java b/src/jalview/ws2/WebServiceWorkerI.java
index 38c82a2..6f3ef9f 100644 (file)
--- a/src/jalview/ws2/WebServiceWorkerI.java
+++ b/src/jalview/ws2/WebServiceWorkerI.java
@@ -5,18 +5,51 @@ import java.util.List;
 
 import jalview.ws2.utils.WSJobList;
 
+/**
+ * {@link WebServiceWorkerI} interface is an extension of {@link PollableTaskI}
+ * that adds getter methods for fields that are specific for the web service
+ * tasks such as uid, sub-jobs and underlying web service client as well as a
+ * method to add listeners to the worker events. {@link WebServiceWorkerI}
+ * objects perform operations needed to start, poll and finalize jobs running on
+ * the server as well as store sub-jobs created in the process. They use their
+ * associated {@link WebServiceI} object to submit and poll the jobs and fetch
+ * and parse the result when it's ready.
+ * 
+ * @author mmwarowny
+ *
+ */
 public interface WebServiceWorkerI extends PollableTaskI
-{  
+{
+  /**
+   * Get unique identifier of this worker. Identifier should be randomly
+   * generated on object creation and must remain unchanged. Unique id can be
+   * generated using {@link jalview.util.MathUtils#getUID}.
+   * 
+   * @return worker unique id
+   */
   long getUID();
 
+  /**
+   * Get the sub-jobs created by the worker during job submission.
+   * 
+   * @return sub-jobs
+   */
   WSJobList getJobs();
 
+  /**
+   * Gather and parse input data and submit one or more jobs to the web service
+   * using associated {@link WebServiceI} object.
+   */
   void start() throws IOException;
 
   boolean poll() throws IOException;
 
   WebServiceI getWebService();
 
+  /**
+   * Check if all sub-jobs finished execution and return whether this task has
+   * completed.
+   */
   default boolean isDone()
   {
     if (getJobs().size() == 0)
@@ -29,11 +62,14 @@ public interface WebServiceWorkerI extends PollableTaskI
     return true;
   }
 
-  /*
-   * Called by the executor when the worker transitions to the done state
-   * either normally or exceptionally.
-   */
   void done();
-  
+
+  /**
+   * Add worker listeners to this worker that will be notified about any state
+   * changes to this worker.
+   * 
+   * @param listener
+   *          listener to add
+   */
   public void addListener(WebServiceWorkerListener listener);
 }