added SeqSearch service interface. Documented and refactored web service client ...

[jalview.git] / src / jalview / ws / WSThread.java

diff --git a/src/jalview/ws/WSThread.java b/src/jalview/ws/WSThread.java
index a23dfe1..a9e9b0b 100644 (file)
--- a/src/jalview/ws/WSThread.java
+++ b/src/jalview/ws/WSThread.java
@@ -23,6 +23,7 @@ import javax.swing.*;
 import jalview.bin.*;
 import jalview.datamodel.*;
 import jalview.gui.*;
+import jalview.gui.FeatureRenderer.FeatureRendererSettings;
 
 public abstract class WSThread
     extends Thread
@@ -30,10 +31,29 @@ public abstract class WSThread
   /**
    * Generic properties for Web Service Client threads.
    */
-  AlignFrame alignFrame = null;
+  /**
+   * 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
@@ -43,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;
     /**
      *
@@ -59,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)
     {
@@ -142,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;
 
@@ -277,13 +352,26 @@ public abstract class WSThread
     else
     {
       Cache.log.debug("WebServiceJob poll loop finished with no jobs created.");
+      wsInfo.setFinishedNoResults();
     }
   }
 
+  /**
+   * 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)
@@ -320,10 +408,19 @@ public abstract class WSThread
     this(alignFrame, wsinfo, input, wsUrl);
     WebServiceName = webServiceName;
   }
+  char defGapChar = '-';
+  /**
+   * 
+   * @return gap character to use for any alignment generation
+   */
+  public char getGapChar()
+  {
+    return defGapChar;
+  }
 
   /**
    * 
-   * @param alframe - reference for copying mappings across
+   * @param alframe - reference for copying mappings and display styles across
    * @param wsinfo2 - gui attachment point
    * @param alview - input data for the calculation
    * @param wsurl2 - url of the service being invoked
@@ -332,15 +429,21 @@ public abstract class WSThread
           AlignmentView alview, String wsurl2)
   {
     super();
-    this.alignFrame = alframe;
+    // this.alignFrame = alframe;
+    currentView = alframe.getCurrentView().getAlignment();
+    featureSettings = alframe.getFeatureRenderer().getSettings();
+    defGapChar = alframe.getViewport().getGapCharacter();
     this.wsInfo = wsinfo2;
     this.input = alview;
     WsUrl = wsurl2;
-    if (alignFrame!=null)
+    if (alframe!=null)
     {
-      AlignedCodonFrame[] cf = alignFrame.getViewport().getAlignment().getCodonFrames();
-      codonframe = new AlignedCodonFrame[cf.length];
-      System.arraycopy(cf, 0, codonframe, 0, cf.length);
+      AlignedCodonFrame[] cf = alframe.getViewport().getAlignment().getCodonFrames();
+      if (cf!=null)
+      {
+        codonframe = new AlignedCodonFrame[cf.length];
+        System.arraycopy(cf, 0, codonframe, 0, cf.length);
+      }
     }
   }
 }