package jalview.ws2;
+/**
+ * The listener interface for receiving signals from the
+ * {@link WebServiceWorkerI} about the state changes or new sub-jobs spawned.
+ *
+ * The {@link WebServiceWorkerListener} objects created from that interface are
+ * then registered with a worker objects using
+ * {@link WebServiceWorkerI#addListener} method. When an event occurs, a
+ * relevant method in the listener is invoked with the worker that emitted the
+ * signal as a first parameter and, optionally, followed by additional event
+ * details.
+ *
+ * @author mmwarowny
+ *
+ */
public interface WebServiceWorkerListener
{
+ /**
+ * Called when the worker started successfully.
+ *
+ * @param source
+ * worker that emitted the signal
+ */
void workerStarted(WebServiceWorkerI source);
-
+
+ /**
+ * Called when the worker failed to start the jobs.
+ *
+ * @param source
+ * worker that emitted the signal
+ */
void workerNotStarted(WebServiceWorkerI source);
-
+
+ /**
+ * Called when the worker creates a new job
+ *
+ * @param source
+ * worker that emitted the signal
+ * @param job
+ * newly created job
+ */
void jobCreated(WebServiceWorkerI source, WSJob job);
-
+
+ /**
+ * Called when polling the job results in an exception.
+ *
+ * @param source
+ * worker that emitted the signal
+ * @param job
+ * polled job
+ * @param e
+ * exception that occurred
+ */
void pollException(WebServiceWorkerI source, WSJob job, Exception e);
-
+
+ /**
+ * Called when the polling has finished and the finalization process begun.
+ *
+ * @param source
+ * worker that emitted the signal
+ */
void workerCompleting(WebServiceWorkerI source);
-
+
+ /**
+ * Called when the worker completes its work.
+ *
+ * @param source
+ * worker that emitted the signal
+ */
void workerCompleted(WebServiceWorkerI source);
}