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