import java.io.IOException;
import java.util.List;
-import javax.print.attribute.standard.JobState;
+import jalview.ws2.utils.WSJobList;
-import jalview.util.MathUtils;
-
-public interface WebServiceWorkerI
+/**
+ * {@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();
- List<WSJob> getJobs();
+ /**
+ * Get the sub-jobs created by the worker during job submission.
+ *
+ * @return sub-jobs
+ */
+ WSJobList getJobs();
- void startJobs() throws IOException;
+ /**
+ * 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 pollJobs() 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);
}