JAL-3878 Add javadocs to created classes and reformat code.

[jalview.git] / src / jalview / ws2 / WebServiceI.java

diff --git a/src/jalview/ws2/WebServiceI.java b/src/jalview/ws2/WebServiceI.java
index 954bab7..cdb201e 100755 (executable)
--- a/src/jalview/ws2/WebServiceI.java
+++ b/src/jalview/ws2/WebServiceI.java
@@ -10,42 +10,93 @@ 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.
+ * 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.
+ * 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();
-  public String getName();
-  public String getDescription();
-  public String getOperationType();
-  public List<Operation> getOperations();
-  public boolean hasParameters();
+
+  /**
+   * 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;
-
-  public void updateProgress(WSJob job)
       throws IOException;
 
-//  public <T> ResultSupplier<T> getResultSupplier(Class<T> type);
+  /**
+   * 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.
+   * 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);