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 1c40eb8..6f3ef9f 100644 (file)
--- a/src/jalview/ws2/WebServiceWorkerI.java
+++ b/src/jalview/ws2/WebServiceWorkerI.java
@@ -3,71 +3,73 @@ package jalview.ws2;
 import java.io.IOException;
 import java.util.List;
 
-import javax.print.attribute.standard.JobState;
-
-import jalview.util.MathUtils;
-
-public interface WebServiceWorkerI
+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
 {
-  public class WSJob
+  /**
+   * 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()
   {
-    public final long uid = MathUtils.getUID();
-    
-    protected WSJobState state = WSJobState.UNKNOWN;
-
-    protected String jobID = "";
-
-    protected int jobNum = 0;
-
-    protected int allowedExceptions = 3;
-
-    public long getUID() {
-      return uid;
-    }
-    
-    public WSJobState getState()
-    {
-      return state;
-    }
-
-    public void setState(WSJobState state)
-    {
-      this.state = state;
-    }
-
-    public String getJobID()
-    {
-      return jobID;
-    }
-
-    public void setJobID(String jobID) {
-      this.jobID = jobID;
-    }
-    
-    public int getJobNum()
-    {
-      return jobNum;
-    }
-
-    public int getAllowedExceptions()
+    if (getJobs().size() == 0)
+      return false;
+    for (WSJob job : getJobs())
     {
-      return allowedExceptions;
-    }
-    
-    public boolean deductAllowedExceptions() {
-      return allowedExceptions-- > 0;
-    }
-    
-    public void resetAllowedExceptions() {
-      allowedExceptions = 3;
+      if (!job.getStatus().isDone() && !job.getStatus().isFailed())
+        return false;
     }
+    return true;
   }
 
-  public long getUID();
-
-  public List<WSJob> getJobs();
-
-  public WSJobID startJob(WSJob job) throws IOException;
+  void done();
 
-  public boolean pollJob(WSJob job) throws IOException;
+  /**
+   * 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);
 }