Merge branch 'JAL-3878_ws-overhaul-3' into mmw/Release_2_12_ws_merge

[jalview.git] / src / jalview / ws2 / client / api / WebServiceClientI.java

diff --git a/src/jalview/ws2/client/api/WebServiceClientI.java b/src/jalview/ws2/client/api/WebServiceClientI.java
new file mode 100644 (file)
index 0000000..49d097e
--- /dev/null
+++ b/src/jalview/ws2/client/api/WebServiceClientI.java
@@ -0,0 +1,103 @@
+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;
+}