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    * List the urls used by this discoverer.
  29    */
  30   List<URL> getUrls();
  31
  32   /**
  33    * Set the list of urls where the discoverer will search for services.
  34    */
  35   void setUrls(List<URL> wsUrls);
  36
  37   /**
  38    * Test if the url is a valid url for that discoverer.
  39    */
  40   default boolean testUrl(URL url)
  41   {
  42     return getStatusForUrl(url) == STATUS_OK;
  43   }
  44
  45   /**
  46    * Get the availability status of the services at the url. Return one of the
  47    * status codes {@code STATUS_OK}, {@code STATUS_NO_SERVICES},
  48    * {@code STATUS_INVALID} or {@code STATUS_UNKNOWN}.
  49    *
  50    * @return services availability status
  51    */
  52   int getStatusForUrl(URL url);
  53
  54   /**
  55    * @return {@value true} if there are services available
  56    */
  57   boolean hasServices();
  58
  59   /**
  60    * Check if service discovery is still in progress. List of services may be
  61    * incomplete when the discoverer is running.
  62    *
  63    * @return whether the discoverer is running
  64    */
  65   boolean isRunning();
  66
  67   /**
  68    * Check if the discoverer is done searching for services. List of services
  69    * should be complete if this methods returns true.
  70    *
  71    * @return whether the discoverer finished
  72    */
  73   boolean isDone();
  74
  75   /**
  76    * Start the service discovery and return a future which will be set to the
  77    * discovery result when the process is completed. This method should be
  78    * called once on startup and then every time the urls list is updated.
  79    *
  80    * @return services list future result
  81    */
  82   CompletableFuture<List<WebService<?>>> startDiscoverer();
  83
  84   /**
  85    * An interface for the services list observers.
  86    *
  87    * @author mmwarowny
  88    */
  89   @FunctionalInterface
  90   interface ServicesChangeListener extends EventListener
  91   {
  92     /**
  93      * Called whenever the services list of the observed discoverer changes with
  94      * that discoverer as the first argument and current services list as the
  95      * second. The list can be empty if there are no services or the list was
  96      * cleared at the beginning of the discovery.
  97      *
  98      * @param discoverer
  99      * @param list
 100      */
 101     public void servicesChanged(WebServiceDiscovererI discoverer,
 102         List<WebService<?>> services);
 103   }
 104
 105   /**
 106    * Add a services list observer that will be notified of any changes to the
 107    * services list.
 108    *
 109    * @param listener
 110    *          services list change listener
 111    */
 112   public void addServicesChangeListener(ServicesChangeListener listener);
 113
 114   /**
 115    * Remove a listener from the listeners list.
 116    *
 117    * @param listener
 118    *          listener to be removed
 119    */
 120   public void removeServicesChangeListener(ServicesChangeListener listener);
 121 }