package jalview.ws2;

import java.io.IOException;
import java.util.List;

import jalview.datamodel.SequenceI;
import jalview.ws.params.ArgumentI;
import jalview.ws.params.ParamDatastoreI;
import jalview.ws.params.WsParamSetI;
import jalview.ws2.operations.Operation;

/**
 * Provides information about the web service and sub-routines to submit, track
 * and cancel the jobs running on the server as well as retrieve the results.
 * The instances should not depend on any other jalview components, especially
 * must be oblivious to the existence of any UI. They are used by other classes
 * such as WebServiceWorkers rather than manipulate data themselves.
 *
 * @author mmwarowny
 */
public interface WebServiceI
{
  /**
   * Get the hostname/url of the remote server which is supplying the service.
   * 
   * @return host name
   */
  public String getHostName();

  /**
   * Get the short name of the service supplier.
   * 
   * @return short service supplier name
   */
  public String getProviderName();

  /**
   * Get the name of the service
   * 
   * @return service name
   */
  String getName();

  /**
   * Get the description of the service.
   * 
   * @return service description
   */
  String getDescription();

  /**
   * Return whether the service provider user-adjustable parameters.
   * 
   * @return whether service has parameters
   */
  boolean hasParameters();

  /**
   * Get a {@link ParamDatastoreI} object containing service parameters and
   * presets.
   * 
   * @return service parameters and presets
   */
  public ParamDatastoreI getParamStore();

  /**
   * Submit new job to the service with the supplied input sequences and
   * arguments. Implementations should perform all data parsing necessary for
   * the job submission and start a new job on the remote server.
   * 
   * @param sequences
   *          input sequences
   * @param args
   *          user provided arguments
   * @return job id
   * @throws IOException
   *           submission failed due to a connection error
   */
  public String submit(List<SequenceI> sequences, List<ArgumentI> args)
      throws IOException;

  /**
   * Update the progress of the running job according to the state reported by
   * the server. Implementations should fetch the current job status from the
   * server and update status and log messages on the provided job object.
   * 
   * @param job
   *          job to update
   * @throws IOException
   *           server error occurred
   */
  public void updateProgress(WSJob job) throws IOException;

  public void cancel(WSJob job) throws IOException;

  /**
   * Handle an exception that happened during job submission. If the exception
   * was handled property by this method, it returns true. Otherwise, returns
   * false indicating the exception should be handled by the caller.
   */
  public boolean handleSubmissionError(WSJob job, Exception ex);

  public boolean handleCollectionError(WSJob job, Exception ex);

}