JAL-3878 Add javadocs to created classes and reformat code.

[jalview.git] / src / jalview / ws2 / WebServiceWorkerListener.java

diff --git a/src/jalview/ws2/WebServiceWorkerListener.java b/src/jalview/ws2/WebServiceWorkerListener.java
index 16ee7bd..74eb144 100644 (file)
--- a/src/jalview/ws2/WebServiceWorkerListener.java
+++ b/src/jalview/ws2/WebServiceWorkerListener.java
@@ -1,16 +1,72 @@
 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);
 }