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

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

diff --git a/src/jalview/ws2/WebServiceWorkerListenersList.java b/src/jalview/ws2/WebServiceWorkerListenersList.java
index a09c958..bce6d57 100644 (file)
--- a/src/jalview/ws2/WebServiceWorkerListenersList.java
+++ b/src/jalview/ws2/WebServiceWorkerListenersList.java
@@ -4,67 +4,136 @@ import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.function.Consumer;
 
+/**
+ * Utility class that manages a list of {@link WebServiceWorkerListener} and
+ * dispatches signals to them. An instance of this class can be used as a member
+ * field of the {@link WebServiceWorkerI} object to easily store listeners and
+ * delegate signals to them. Firing any signal with this object will invoke a
+ * corresponding method on all registered listeners in order they were
+ * registered.
+ * 
+ * @author mmwarowny
+ *
+ */
 public class WebServiceWorkerListenersList
 {
   private WebServiceWorkerI owner;
+
   private List<WebServiceWorkerListener> listeners = new CopyOnWriteArrayList<>();
-  
+
+  /**
+   * Constructs a listeners list object with the worker which will be given
+   * to the listeners as the source of the signals.
+   * 
+   * @param worker the worker to be given as the source for signals
+   */
   public WebServiceWorkerListenersList(WebServiceWorkerI worker)
   {
     this.owner = worker;
   }
-  
+
+  /**
+   * Add listener to the listeners list. The listener will be notified of
+   * any signals triggered with this object.
+   * 
+   * @param listener listener to add
+   */
   public void addListener(WebServiceWorkerListener listener)
   {
     listeners.add(listener);
   }
-  
+
+  /**
+   * Remove listener from the lsiteners list. The listener will no longer be
+   * notified of the emitted signals.
+   * 
+   * @param listener listener to remove
+   */
   public void removeListener(WebServiceWorkerListener listener)
   {
     listeners.remove(listener);
   }
-  
+
+  /**
+   * Emit "worker started" signal to all listeners.
+   */
   public void fireWorkerStarted()
   {
     for (var listener : listeners)
       listener.workerStarted(owner);
   }
-  
+
+  /**
+   * Emit "worker not started" signal to all listeners.
+   */
   public void fireWorkerNotStarted()
   {
     for (var listener : listeners)
       listener.workerNotStarted(owner);
   }
-  
+
+  /**
+   * Emit "job created" signal to all listeners passing the job that has been
+   * created to them.
+   * 
+   * @param job newly created job
+   */
   public void fireJobCreated(WSJob job)
   {
     for (var listener : listeners)
       listener.jobCreated(owner, job);
   }
-  
+
+  /**
+   * Emit "poll exception" signal to all listener when an exception occurred
+   * during job polling. The job which caused an exception as well as the exception
+   * are passed to all listeners.
+   * 
+   * @param job polled job
+   * @param e exception that occurred
+   */
   public void firePollException(WSJob job, Exception e)
   {
     for (var listener : listeners)
       listener.pollException(owner, job, e);
   }
-  
+
+  /**
+   * Emit "worker completing" signal to all listeners when the worker starts
+   * collecting and parsing the results.
+   */
   public void fireWorkerCompleting()
   {
     for (var listener : listeners)
       listener.workerCompleting(owner);
   }
-  
+
+  /**
+   * Emit "worker completed" signal to all listeners indicating that the worker
+   * finished processing data and finalized the jobs. 
+   */
   public void fireWorkerCompleted()
   {
     for (var listener : listeners)
       listener.workerCompleted(owner);
   }
   
+  /**
+   * Get the list of registered listeners. The returned list should not be
+   * modified externally and its content may change when workers are added
+   * or removed from the list.
+   * @return
+   */
   public List<WebServiceWorkerListener> getListeners()
   {
     return listeners;
   }
-  
+
+  /**
+   * Execute an operation for each listener in the listeners list.
+   * 
+   * @param consumer listener object consumer 
+   */
   public void forEach(Consumer<WebServiceWorkerListener> consumer)
   {
     for (var listener : listeners)