From: jprocter Date: Thu, 17 Apr 2008 15:06:02 +0000 (+0000) Subject: javadoc for webservice client tutorial X-Git-Tag: Release_2_4~114 X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=229f08966955df51cc6feac709b8b47474488bbd;p=jalview.git javadoc for webservice client tutorial --- diff --git a/src/jalview/ws/WSClient.java b/src/jalview/ws/WSClient.java index 8c9acb5..cf871b8 100755 --- 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 --- 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 --- 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 codonframe to al + * @param al + */ protected void propagateDatasetMappings(Alignment al) { if (codonframe!=null)