src/jalview/ws2/WebServiceDiscovererI.java

   1 package jalview.ws2;
   2
   3 import java.net.URL;
   4 import java.util.ArrayList;
   5 import java.util.Collection;
   6 import java.util.List;
   7 import java.util.concurrent.CompletableFuture;
   8 import java.util.concurrent.CopyOnWriteArrayList;
   9
  10 import jalview.ws2.operations.Operation;
  11
  12 /**
  13  * The discoverer and the supplier of the operations/web services available
  14  * on the remote hosts. Each web service client used should have it's
  15  * implementation of the discoverer acting as an intermediary between the servers
  16  * and jalview application. There is no need for more than one discoverer
  17  * per web client per application, therefore singletons can be used.
  18  *
  19  * The discoverer stores a list of url endpoints where the services can be
  20  * found and builds instances of {@link jalview.ws2.operations.Operation}
  21  * with associated implementations of {@link jalview.ws2.WebServiceI}.
  22  *
  23  * @author mmwarowny
  24  *
  25  */
  26 public interface WebServiceDiscovererI
  27 {
  28   public static final int STATUS_OK = 1;
  29
  30   public static final int STATUS_NO_SERVICES = 0;
  31
  32   public static final int STATUS_INVALID = -1;
  33
  34   public static final int STATUS_UNKNOWN = -2;
  35
  36   /**
  37    * Get the list of urls that this discoverer will use.
  38    */
  39   public List<String> getUrls();
  40
  41   /**
  42    * Set the list of urls where this discoverer will search for services.
  43    */
  44   public void setUrls(List<String> wsUrls);
  45
  46   /**
  47    * Test if the url is a valid url for that service discoverer.
  48    */
  49   public boolean testUrl(URL url);
  50
  51   /**
  52    * Get the availability status of the services at the url. Return one of the
  53    * status codes {@code STATUS_OK}, {@code STATUS_NO_SERVICES},
  54    * {@code STATUS_INVALID} or {@code STATUS_UNKNOWN}.
  55    *
  56    * @return status code for the services availability
  57    */
  58   public int getStatusForUrl(String url);
  59
  60   /**
  61    * Get the list of operations found on the servers.
  62    *
  63    * @return list of operations found
  64    */
  65   public List<Operation> getOperations();
  66
  67   /**
  68    * @return whether there are services found
  69    */
  70   public boolean hasServices();
  71
  72   /**
  73    * Check if service discovery is still in progress. List of operations may be
  74    * incomplete when the discoverer is running.
  75    *
  76    * @return whether the discoverer is running
  77    */
  78   public boolean isRunning();
  79
  80   /**
  81    * Check if the discoverer is done searching for services. List of operations
  82    * should be complete if this methods returns true.
  83    *
  84    * @return whether the discoverer finished
  85    */
  86   public boolean isDone();
  87
  88   /**
  89    * Start the service discovery and return a future which will be set with this
  90    * discoverer when the process is completed. This method should be called once
  91    * on startup and then every time the urls list is updated.
  92    *
  93    * @return future that will be set on discovery completion
  94    */
  95   public CompletableFuture<WebServiceDiscovererI> startDiscoverer();
  96
  97   /**
  98    * Get the error messages that occurred during service discovery.
  99    *
 100    * @return error message
 101    */
 102   public String getErrorMessages();
 103
 104   /**
 105    * An interface for the listeners observing the changes to the operations
 106    * list.
 107    *
 108    * @author mmwarowny
 109    */
 110   @FunctionalInterface
 111   static interface OperationsChangeListener
 112   {
 113     /**
 114      * Called whenever the operations list of the observed discoverer changes
 115      * with that discoverer as the first argument and current operations list as
 116      * the second. Operations list can be empty if there are no services or the
 117      * list was cleared at the beginning of the discovery.
 118      *
 119      * @param discoverer
 120      * @param list
 121      */
 122     public void operationsChanged(WebServiceDiscovererI discoverer,
 123         List<Operation> operations);
 124   }
 125
 126   /**
 127    * Add an operations list observer that will be notified of any changes.
 128    *
 129    * @param listener
 130    *          operations list listener
 131    */
 132   public void addOperationsChangeListener(OperationsChangeListener listener);
 133
 134   /**
 135    * Remove the listener from the observers list.
 136    *
 137    * @param listener
 138    *          listener to be removed
 139    */
 140   public void removeOperationsChangeListener(OperationsChangeListener listener);
 141 }