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