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)
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);
}