package jalview.ws2.client.api;

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

import jalview.datamodel.SequenceI;
import jalview.ws.params.ArgumentI;
import jalview.ws2.api.Credentials;
import jalview.ws2.api.JobStatus;
import jalview.ws2.api.WebServiceJobHandle;

/**
 * A common interface for all web service clients that provide methods to get
 * the URL of the server the client is talking to, submit new jobs to the server
 * as well as poll or cancel the running jobs. This interface does not provide
 * means to retrieve job results as those may differ between web services.
 * Specialized sub-interfaces define methods to retrieve job results appropriate
 * for specific service types.
 * 
 * @author mmwarowny
 *
 */
public interface WebServiceClientI
{
  /**
   * Get the hostname/url of the remote server which is supplying the service.
   * 
   * @return host name
   */
  String getUrl();

  /**
   * Get the name of the web service client.
   * 
   * @return client name
   */
  String getClientName();

  /**
   * Submit new job to the service with the supplied input sequences and
   * arguments. Optionally, some services may require additional credentials to
   * run. Implementations should perform all data serialization necessary for
   * the job submission, start a new job on the remote server and return a
   * handler for that job.
   * 
   * @param sequences
   *          input sequences
   * @param args
   *          user provided arguments
   * @param credentials
   *          optional user credentials needed to run the job
   * @return job handler
   * @throws IOException
   *           submission failed due to a connection error
   */
  WebServiceJobHandle submit(List<SequenceI> sequences, List<ArgumentI> args,
      Credentials credentials) throws IOException;

  /**
   * Poll the server to get the current status of the job.
   * 
   * @param job
   *          web service job
   * @return job status
   * @throws IOException
   *           server communication error
   */
  JobStatus getStatus(WebServiceJobHandle job) throws IOException;

  /**
   * Retrieve log messages from the server for the job.
   * 
   * @param job
   *          web service job
   * @return log content
   * @throws IOException
   *           server communication error
   */
  String getLog(WebServiceJobHandle job) throws IOException;

  /**
   * Retrieve error log messages from the server for the job.
   * 
   * @param job
   *          web service job
   * @return error log content
   * @throws IOException
   *           server communication error
   */
  String getErrorLog(WebServiceJobHandle job) throws IOException;

  /**
   * Send the cancellation request to the server for the specified job.
   * 
   * @param job
   *          job to cancel
   * @throws IOException
   *           server error occurred
   * @throws UnsupportedOperationException
   *           server does not support job cancellation
   */
  void cancel(WebServiceJobHandle job) throws IOException, UnsupportedOperationException;
}