src/jalview/ws2/client/api/WebServiceClientI.java

   1 package jalview.ws2.client.api;
   2
   3 import java.io.IOException;
   4 import java.util.List;
   5
   6 import jalview.datamodel.SequenceI;
   7 import jalview.ws.params.ArgumentI;
   8 import jalview.ws2.api.Credentials;
   9 import jalview.ws2.api.WebServiceJob;
  10
  11 /**
  12  * A common interface for all web service clients that provide methods to
  13  * get the URL of the server the client is talking to, submit new jobs to the
  14  * server as well as poll or cancel the running jobs. This interface does not
  15  * provide means to retrieve job results as those may differ between
  16  * web services. Specialized sub-interfaces define methods to retrieve job
  17  * results appropriate for specific service types.
  18  *
  19  * @author mmwarowny
  20  *
  21  */
  22 public interface WebServiceClientI
  23 {
  24   /**
  25    * Get the hostname/url of the remote server which is supplying the service.
  26    *
  27    * @return host name
  28    */
  29   String getUrl();
  30
  31   /**
  32    * Get the name of the web service client.
  33    *
  34    * @return client name
  35    */
  36   String getClientName();
  37
  38   /**
  39    * Submit new job to the service with the supplied input sequences and
  40    * arguments. Optionally, some services may require additional credentials to
  41    * run. Implementations should perform all data serialization necessary for
  42    * the job submission, start a new job on the remote server and return a
  43    * handler for that job.
  44    *
  45    * @param sequences
  46    *          input sequences
  47    * @param args
  48    *          user provided arguments
  49    * @param credentials
  50    *          optional user credentials needed to run the job
  51    * @return job handler
  52    * @throws IOException
  53    *           submission failed due to a connection error
  54    */
  55   WebServiceJob submit(List<SequenceI> sequences, List<ArgumentI> args,
  56       Credentials credentials) throws IOException;
  57
  58   /**
  59    * Poll the server and update the progress of the running job accordingly.
  60    * Implementations should fetch the current job status from the server and
  61    * update the status and log strings on the provided job object.
  62    *
  63    * @param job
  64    *          job to update
  65    * @throws IOException
  66    *           server error occurred
  67    */
  68   void updateProgress(WebServiceJob job) throws IOException;
  69
  70   /**
  71    * Send the cancellation request to the server for the specified job.
  72    *
  73    * @param job
  74    *          job to cancel
  75    * @throws IOException
  76    *           server error occurred
  77    * @throws UnsupportedOperationException
  78    *           server does not support job cancellation
  79    */
  80   void cancel(WebServiceJob job) throws IOException, UnsupportedOperationException;
  81 }