X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fws2%2FWebServiceWorkerI.java;h=6f3ef9ff2e6b3f4bbacdbb711b0862aef089cb24;hb=2bbba7f7426314bfd6a1f206861542244b5f511a;hp=38c82a20a1940067639a20b48e040af3e3d8ff92;hpb=158e0595615ae4bfb13554f41f03b570642f6bb2;p=jalview.git

diff --git a/src/jalview/ws2/WebServiceWorkerI.java b/src/jalview/ws2/WebServiceWorkerI.java
index 38c82a2..6f3ef9f 100644
--- 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);
 }