javadoc for webservice client tutorial

diff --git a/src/jalview/ws/WSClient.java b/src/jalview/ws/WSClient.java
index 8c9acb5..cf871b8 100755 (executable)
--- a/src/jalview/ws/WSClient.java
+++ b/src/jalview/ws/WSClient.java
@@ -24,17 +24,35 @@ import jalview.gui.*;
 public class WSClient
 {
   /**
-   * MsaWSClient
-   *
-   * @param msa SequenceI[]
+   * WSClient holds the basic attributes that are displayed to the user
+   * for all jalview web service clients
+   */
+  /**
+   * displayed name for this web service
    */
   protected String WebServiceName;
+  /**
+   * specific job title (e.g. 'ClustalW Alignment of Selection from Aligment from Cut and Paste input')
+   */
   protected String WebServiceJobTitle;
+  /**
+   * String giving additional information such as method citations for this service 
+   */
   protected String WebServiceReference;
+  /**
+   * Service endpoint
+   */
   protected String WsURL;
+  /**
+   * Web service information used to initialise the WSClient attributes
+   */
   protected WebserviceInfo wsInfo;
+  /**
+   * total number of jobs managed by this web service client instance. 
+   */
   int jobsRunning = 0;
   /**
+   * TODO: this is really service metadata, and should be moved elsewhere.
    * mappings between abstract interface names and menu entries
    */
   protected java.util.Hashtable ServiceActions;
@@ -46,7 +64,11 @@ public class WSClient
   public WSClient()
   {
   }
-
+  /**
+   * initialise WSClient service information attributes from the service handle
+   * @param sh
+   * @return the service instance information for this client and job.
+   */
   protected WebserviceInfo setWebService(ServiceHandle sh)
   {
     WebServiceName = sh.getName();

diff --git a/src/jalview/ws/WSClientI.java b/src/jalview/ws/WSClientI.java
index d3f473f..7a2b212 100755 (executable)
--- a/src/jalview/ws/WSClientI.java
+++ b/src/jalview/ws/WSClientI.java
@@ -21,16 +21,20 @@ package jalview.ws;
 public interface WSClientI
 {
   /**
+   * basic interface supported by web service clients 
+   */
+  /**
    *
    * @return boolean true if job is cancellable
    */
   boolean isCancellable();
 
   /**
-   *
    * @return boolean true if results can be merged into the source of input data
    */
   boolean canMergeResults();
-
+  /**
+   * instruct client to cancel the job
+   */
   void cancelJob();
 }

diff --git a/src/jalview/ws/WSThread.java b/src/jalview/ws/WSThread.java
index a69e434..b81a38f 100644 (file)
--- a/src/jalview/ws/WSThread.java
+++ b/src/jalview/ws/WSThread.java
@@ -31,11 +31,29 @@ public abstract class WSThread
   /**
    * Generic properties for Web Service Client threads.
    */
+  /**
+   * view that this job was associated with
+   */
   AlignmentI currentView = null;
+  /**
+   * feature settings from view that job was associated with
+   */
   FeatureRendererSettings featureSettings = null;
+  /**
+   * metadata about this web service
+   */
   WebserviceInfo wsInfo = null;
+  /**
+   * original input data for this job
+   */
   AlignmentView input = null;
+  /**
+   * dataset sequence relationships to be propagated onto new results
+   */
   AlignedCodonFrame[] codonframe = null;
+  /**
+   * are there jobs still running in this thread.
+   */
   boolean jobComplete = false;
   
   abstract class WSJob
@@ -45,9 +63,21 @@ public abstract class WSThread
      */
     int jobnum = 0; // WebServiceInfo pane for this job
     String jobId; // ws job ticket
+    /**
+     * has job been cancelled
+     */
     boolean cancelled = false;
-    int allowedServerExceptions = 3; // job dies if too many exceptions.
+    /**
+     * number of exceptions left before job dies
+     */
+    int allowedServerExceptions = 3;
+    /**
+     * has job been submitted
+     */
     boolean submitted = false;
+    /**
+     * are all sub-jobs complete
+     */
     boolean subjobComplete = false;
     /**
      *
@@ -61,18 +91,48 @@ public abstract class WSThread
      */
     abstract boolean hasValidInput();
 
+    /**
+     * The last result object returned by the service.
+     */
     vamsas.objects.simple.Result result;
   }
 
   class JobStateSummary
   {
+    /**
+     * number of jobs running
+     */
     int running = 0;
+    /**
+     * number of jobs queued
+     */
     int queuing = 0;
+    /**
+     * number of jobs finished
+     */
     int finished = 0;
+    /**
+     * number of jobs failed
+     */
     int error = 0;
+    /**
+     * number of jobs stopped due to server error
+     */
     int serror = 0;
+    /**
+     * number of jobs cancelled
+     */
     int cancelled = 0;
+    /**
+     * number of jobs finished with results
+     */
     int results = 0;
+    /**
+     * processes WSJob and updates job status counters and WebService status displays
+     * @param wsInfo
+     * @param OutputHeader
+     * @param j
+     */
     void updateJobPanelState(WebserviceInfo wsInfo, String OutputHeader,
                              WSJob j)
     {
@@ -144,11 +204,24 @@ public abstract class WSThread
       }
     }
   }
-
+  /**
+   * one or more jobs being managed by this thread.
+   */
   WSJob jobs[] = null;
+  /**
+   * full name of service
+   */
   String WebServiceName = null;
   String OutputHeader;
   String WsUrl = null;
+  /**
+   * query web service for status of job.
+   * on return, job.result must not be null - if it is then it will be
+   * assumed that the job status query timed out and a server exception
+   * will be logged.
+   * @param job
+   * @throws Exception will be logged as a server exception for this job
+   */
   abstract void pollJob(WSJob job)
       throws Exception;
 
@@ -282,10 +355,22 @@ public abstract class WSThread
     }
   }
 
+  /**
+   * submit job to web service
+   * @param job
+   */
   abstract void StartJob(WSJob job);
 
+  /**
+   * process the set of WSJob objects into a set of results, and tidy up.
+   */
   abstract void parseResult();
 
+  /**
+   * helper function to conserve dataset references to sequence objects returned from web services
+   * 1. Propagates AlCodonFrame data from <code>codonframe</code> to <code>al</code>
+   * @param al
+   */
   protected void propagateDatasetMappings(Alignment al)
   {
     if (codonframe!=null)