doc/addingWebClient.md

   1 # How to add a web service backend to Jalview's web services UI
   2
   3 ### Document Status: *Work in progress !*
   4
   5 There are two phases to services.
   6
   7  *Discovery* threads are started by jalview.gui.Desktop (or other UI components or the CLI if they are headless services accessible via commandline). Your service discovery thread registers discovered instances so they can be accessed by the user.
   8
   9  *Access* most services are accessed by selecting a menu item, option, or specifying a nickname for the service instance as a Jalview command line parameter. Different access patterns are used for the various services: seqeunce data source, sequence feature annotation source, multiple sequence alignment, multiple alignment annotation source, etc. There should be no need for your code to create UI components (if there is then Jalview's UI needs to be refactored to avoid this).
  10
  11 ## Discovery
  12
  13 *jalview.gui.Desktop*
  14 - start a discovery thread to discover services provided by your framework. The discoverer should generate a list of objects that either implement WsMenuEntryProviderI or provide another mechanism to add themselves to Jalview's menus (via jalview.gui.AlignFrame.BuildWebServiceMenu() below)
  15
  16 *jalview.gui.AlignFrame*
  17 - BuildWebServiceMenu()
  18  This method creates a runnable that's called when the available set of web services changes (e.g. when a discovery thread completes). Add code to the Runnable's run method to create Menu Items in the web services menu via jalview.ws.WSMenuEntryProviderI instances generated by your discoverer.
  19
  20
  21 ## Types of service
  22
  23 ### Services that create new alignments or windows, optionally with a progress log
  24
  25 The pattern for these services requires a Client that initates a thread which creates, and montors one or more jobs based on input data.
  26
  27 jalview.ws.MsaWSClient -- currently does double duty with Jaba services for alignment analysis and instantiation of alignment services.
  28
  29 jalview.ws.gui.MSAThread -- UI model and controller for a running MSA service. Instantiated with an instance of jalview.ws.MultipleSequenceAlignmentI provided by the service endpoint factory.
  30
  31
  32 ## Other classes of interest
  33
  34 ### jalview.ws.api
  35
  36 Interfaces and base classes to be implemented and used by a service endpoint.
  37
  38  jalview.ws.api.CancellableI.java - implement if the service is cancellable
  39  jalview.ws.api.JalviewWebServiceI.java - base service interface
  40  jalview.ws.api.JobId.java - a timestamped job id that can be saved in a Jalview project
  41
  42 #### submission interfaces
  43 jalview.ws.api.MsaI.java
  44 jalview.ws.api.MsaWithGuideTreeI.java
  45
  46
  47 #### result interfaces
  48 jalview.ws.api.MsaResultI.java
  49 jalview.ws.api.TreeResultI.java
  50 jalview.ws.api.DistanceMatrixResultI.java
  51
  52
  53 #### minimal composed interfaces for a complete functional analysis
  54
  55 jalview.ws.api.MultipleSequenceAlignmentI.java
  56
  57
  58 #### base class for a service endpoint instance - to be materialised by service discoverers
  59
  60 jalview.ws.api.UIinfo.java - basic information
  61 jalview.ws.api.ServiceWithParameters.java
  62
  63 jalview.ws.api.JalviewServiceEndpointProviderI - implemented by service endpoint factories (typically extended from UIinfo or ServiceWithParameters).
  64
  65
  66 ## Analysis services
  67
  68 These have not yet been refactored. Feel free to look at how jalview.ws.jws2.AACons and Disorder clients operate and adapt the pattern for your own services. The Groovy example in the help [[help/html/groovy/featuresCounter.html]] for creating custom annotation tracks uses the same basic 'alignment analysis worker' mechanism to provide dynamically executed alignment analysis calculations that result in annotation tracks displayed below the alginment.