src/jalview/ws2/WebServiceDiscoverer.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 WebServiceDiscoverer
  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<WebServiceDiscoverer> 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 ServiceChangeListener
 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(WebServiceDiscoverer discoverer,
 123         List<Operation> list);
 124   }
 125
 126   List<ServiceChangeListener> serviceListeners = new CopyOnWriteArrayList<>();
 127
 128   /**
 129    * Add an operations list observer that will be notified of any changes.
 130    *
 131    * @param listener
 132    *          operations list listener
 133    */
 134   public default void addServiceChangeListener(
 135       ServiceChangeListener listener)
 136   {
 137     serviceListeners.add(listener);
 138   }
 139
 140   /**
 141    * Remove the listener from the observers list.
 142    *
 143    * @param listener
 144    *          listener to be removed
 145    */
 146   public default void removeServiceChangeListener(
 147       ServiceChangeListener listener)
 148   {
 149     serviceListeners.remove(listener);
 150   }
 151
 152   /**
 153    * Called whenever the list of operations changes. Notifies all listeners of
 154    * the change to the operations list. Typically, should be called with an
 155    * empty list at the beginning of the service discovery process and for the
 156    * second time with the list of discovered operations after that.
 157    *
 158    * @param list
 159    *          new list of discovered operations
 160    */
 161   default void fireOperationsChanged(List<Operation> list)
 162   {
 163     for (var listener : serviceListeners)
 164     {
 165       listener.operationsChanged(this, list);
 166     }
 167   }
 168 }