Merge branch 'JAL-3878_ws-overhaul-3' into mmw/Release_2_12_ws_merge

[jalview.git] / src / jalview / ws2 / client / api / WebServiceDiscovererI.java

diff --git a/src/jalview/ws2/client/api/WebServiceDiscovererI.java b/src/jalview/ws2/client/api/WebServiceDiscovererI.java
new file mode 100644 (file)
index 0000000..4a09ef7
--- /dev/null
+++ b/src/jalview/ws2/client/api/WebServiceDiscovererI.java
@@ -0,0 +1,121 @@
+package jalview.ws2.client.api;
+
+import java.net.URL;
+import java.util.EventListener;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+import jalview.ws2.api.WebService;
+
+/**
+ * The discoverer and supplier of web services. The discoverer is responsible
+ * for building and storing {@link jalview.ws2.api.WebService} objects
+ * according to the data retrieved from the servers available at specified urls.
+ * @author mmwarowny
+ *
+ */
+public interface WebServiceDiscovererI extends WebServiceProviderI
+{
+  public static final int STATUS_OK = 1;
+
+  public static final int STATUS_NO_SERVICES = 0;
+
+  public static final int STATUS_INVALID = -1;
+
+  public static final int STATUS_UNKNOWN = -2;
+
+  /**
+   * List the urls used by this discoverer.
+   */
+  List<URL> getUrls();
+
+  /**
+   * Set the list of urls where the discoverer will search for services.
+   */
+  void setUrls(List<URL> wsUrls);
+
+  /**
+   * Test if the url is a valid url for that discoverer.
+   */
+  default boolean testUrl(URL url)
+  {
+    return getStatusForUrl(url) == STATUS_OK;
+  }
+
+  /**
+   * Get the availability status of the services at the url. Return one of the
+   * status codes {@code STATUS_OK}, {@code STATUS_NO_SERVICES},
+   * {@code STATUS_INVALID} or {@code STATUS_UNKNOWN}.
+   * 
+   * @return services availability status
+   */
+  int getStatusForUrl(URL url);
+
+  /**
+   * @return {@value true} if there are services available
+   */
+  boolean hasServices();
+
+  /**
+   * Check if service discovery is still in progress. List of services may be
+   * incomplete when the discoverer is running.
+   * 
+   * @return whether the discoverer is running
+   */
+  boolean isRunning();
+
+  /**
+   * Check if the discoverer is done searching for services. List of services
+   * should be complete if this methods returns true.
+   * 
+   * @return whether the discoverer finished
+   */
+  boolean isDone();
+
+  /**
+   * Start the service discovery and return a future which will be set to the
+   * discovery result when the process is completed. This method should be
+   * called once on startup and then every time the urls list is updated.
+   * 
+   * @return services list future result
+   */
+  CompletableFuture<List<WebService<?>>> startDiscoverer();
+
+  /**
+   * An interface for the services list observers.
+   * 
+   * @author mmwarowny
+   */
+  @FunctionalInterface
+  interface ServicesChangeListener extends EventListener
+  {
+    /**
+     * Called whenever the services list of the observed discoverer changes with
+     * that discoverer as the first argument and current services list as the
+     * second. The list can be empty if there are no services or the list was
+     * cleared at the beginning of the discovery.
+     * 
+     * @param discoverer
+     * @param list
+     */
+    public void servicesChanged(WebServiceDiscovererI discoverer,
+        List<WebService<?>> services);
+  }
+
+  /**
+   * Add a services list observer that will be notified of any changes to the
+   * services list.
+   * 
+   * @param listener
+   *          services list change listener
+   */
+  public void addServicesChangeListener(ServicesChangeListener listener);
+
+  /**
+   * Remove a listener from the listeners list.
+   * 
+   * @param listener
+   *          listener to be removed
+   */
+  public void removeServicesChangeListener(ServicesChangeListener listener);
+}