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);
}