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.JobStatus;
  10 import jalview.ws2.api.WebServiceJobHandle;
  11
  12 /**
  13  * A common interface for all web service clients that provide methods to get
  14  * the URL of the server the client is talking to, submit new jobs to the server
  15  * as well as poll or cancel the running jobs. This interface does not provide
  16  * means to retrieve job results as those may differ between web services.
  17  * Specialized sub-interfaces define methods to retrieve job results appropriate
  18  * for specific service types.
  19  *
  20  * @author mmwarowny
  21  *
  22  */
  23 public interface WebServiceClientI
  24 {
  25   /**
  26    * Get the hostname/url of the remote server which is supplying the service.
  27    *
  28    * @return host name
  29    */
  30   String getUrl();
  31
  32   /**
  33    * Get the name of the web service client.
  34    *
  35    * @return client name
  36    */
  37   String getClientName();
  38
  39   /**
  40    * Submit new job to the service with the supplied input sequences and
  41    * arguments. Optionally, some services may require additional credentials to
  42    * run. Implementations should perform all data serialization necessary for
  43    * the job submission, start a new job on the remote server and return a
  44    * handler for that job.
  45    *
  46    * @param sequences
  47    *          input sequences
  48    * @param args
  49    *          user provided arguments
  50    * @param credentials
  51    *          optional user credentials needed to run the job
  52    * @return job handler
  53    * @throws IOException
  54    *           submission failed due to a connection error
  55    */
  56   WebServiceJobHandle submit(List<SequenceI> sequences, List<ArgumentI> args,
  57       Credentials credentials) throws IOException;
  58
  59   /**
  60    * Poll the server to get the current status of the job.
  61    *
  62    * @param job
  63    *          web service job
  64    * @return job status
  65    * @throws IOException
  66    *           server communication error
  67    */
  68   JobStatus getStatus(WebServiceJobHandle job) throws IOException;
  69
  70   /**
  71    * Retrieve log messages from the server for the job.
  72    *
  73    * @param job
  74    *          web service job
  75    * @return log content
  76    * @throws IOException
  77    *           server communication error
  78    */
  79   String getLog(WebServiceJobHandle job) throws IOException;
  80
  81   /**
  82    * Retrieve error log messages from the server for the job.
  83    *
  84    * @param job
  85    *          web service job
  86    * @return error log content
  87    * @throws IOException
  88    *           server communication error
  89    */
  90   String getErrorLog(WebServiceJobHandle job) throws IOException;
  91
  92   /**
  93    * Send the cancellation request to the server for the specified job.
  94    *
  95    * @param job
  96    *          job to cancel
  97    * @throws IOException
  98    *           server error occurred
  99    * @throws UnsupportedOperationException
 100    *           server does not support job cancellation
 101    */
 102   void cancel(WebServiceJobHandle job) throws IOException, UnsupportedOperationException;
 103 }