src/jalview/ws2/client/api/WebServiceDiscovererI.java

   1 package jalview.ws2.client.api;
   2
   3 import java.net.URL;
   4 import java.util.EventListener;
   5 import java.util.List;
   6 import java.util.concurrent.CompletableFuture;
   7
   8 import jalview.ws2.api.WebService;
   9
  10 /**
  11  * The discoverer and supplier of web services. The discoverer is responsible
  12  * for building and storing {@link jalview.ws2.api.WebService} objects
  13  * according to the data retrieved from the servers available at specified urls.
  14  * @author mmwarowny
  15  *
  16  */
  17 public interface WebServiceDiscovererI extends WebServiceProviderI
  18 {
  19   public static final int STATUS_OK = 1;
  20
  21   public static final int STATUS_NO_SERVICES = 0;
  22
  23   public static final int STATUS_INVALID = -1;
  24
  25   public static final int STATUS_UNKNOWN = -2;
  26
  27   /**
  28    * Get the short name of the discoverer.
  29    *
  30    * @return discoverer name
  31    */
  32   String getName();
  33
  34   /**
  35    * List the urls used by this discoverer.
  36    */
  37   List<URL> getUrls();
  38
  39   /**
  40    * Set the list of urls where the discoverer will search for services.
  41    */
  42   void setUrls(List<URL> wsUrls);
  43
  44   /**
  45    * Test if the url is a valid url for that discoverer.
  46    */
  47   default boolean testUrl(URL url)
  48   {
  49     return getStatusForUrl(url) == STATUS_OK;
  50   }
  51
  52   /**
  53    * Get the availability status of the services at the url. Return one of the
  54    * status codes {@code STATUS_OK}, {@code STATUS_NO_SERVICES},
  55    * {@code STATUS_INVALID} or {@code STATUS_UNKNOWN}.
  56    *
  57    * @return services availability status
  58    */
  59   int getStatusForUrl(URL url);
  60
  61   /**
  62    * @return {@value true} if there are services available
  63    */
  64   boolean hasServices();
  65
  66   /**
  67    * Check if service discovery is still in progress. List of services may be
  68    * incomplete when the discoverer is running.
  69    *
  70    * @return whether the discoverer is running
  71    */
  72   boolean isRunning();
  73
  74   /**
  75    * Check if the discoverer is done searching for services. List of services
  76    * should be complete if this methods returns true.
  77    *
  78    * @return whether the discoverer finished
  79    */
  80   boolean isDone();
  81
  82   /**
  83    * Start the service discovery and return a future which will be set to the
  84    * discovery result when the process is completed. This method should be
  85    * called once on startup and then every time the urls list is updated.
  86    *
  87    * @return services list future result
  88    */
  89   CompletableFuture<List<WebService<?>>> startDiscoverer();
  90
  91   /**
  92    * An interface for the services list observers.
  93    *
  94    * @author mmwarowny
  95    */
  96   @FunctionalInterface
  97   interface ServicesChangeListener extends EventListener
  98   {
  99     /**
 100      * Called whenever the services list of the observed discoverer changes with
 101      * that discoverer as the first argument and current services list as the
 102      * second. The list can be empty if there are no services or the list was
 103      * cleared at the beginning of the discovery.
 104      *
 105      * @param discoverer
 106      * @param list
 107      */
 108     public void servicesChanged(WebServiceDiscovererI discoverer,
 109         List<WebService<?>> services);
 110   }
 111
 112   /**
 113    * Add a services list observer that will be notified of any changes to the
 114    * services list.
 115    *
 116    * @param listener
 117    *          services list change listener
 118    */
 119   public void addServicesChangeListener(ServicesChangeListener listener);
 120
 121   /**
 122    * Remove a listener from the listeners list.
 123    *
 124    * @param listener
 125    *          listener to be removed
 126    */
 127   public void removeServicesChangeListener(ServicesChangeListener listener);
 128 }