4 import java.util.ArrayList;
5 import java.util.Collection;
7 import java.util.concurrent.CompletableFuture;
8 import java.util.concurrent.CopyOnWriteArrayList;
10 import jalview.ws2.operations.Operation;
13 * The discoverer and the supplier of the operations/web services available
14 * on the remote hosts. Each web service client used should have it's
15 * implementation of the discoverer acting as an intermediary between the servers
16 * and jalview application. There is no need for more than one discoverer
17 * per web client per application, therefore singletons can be used.
19 * The discoverer stores a list of url endpoints where the services can be
20 * found and builds instances of {@link jalview.ws2.operations.Operation}
21 * with associated implementations of {@link jalview.ws2.WebServiceI}.
26 public interface WebServiceDiscovererI
28 public static final int STATUS_OK = 1;
30 public static final int STATUS_NO_SERVICES = 0;
32 public static final int STATUS_INVALID = -1;
34 public static final int STATUS_UNKNOWN = -2;
37 * Get the list of urls that this discoverer will use.
39 public List<String> getUrls();
42 * Set the list of urls where this discoverer will search for services.
44 public void setUrls(List<String> wsUrls);
47 * Test if the url is a valid url for that service discoverer.
49 public boolean testUrl(URL url);
52 * Get the availability status of the services at the url. Return one of the
53 * status codes {@code STATUS_OK}, {@code STATUS_NO_SERVICES},
54 * {@code STATUS_INVALID} or {@code STATUS_UNKNOWN}.
56 * @return status code for the services availability
58 public int getStatusForUrl(String url);
61 * Get the list of operations found on the servers.
63 * @return list of operations found
65 public List<Operation> getOperations();
68 * @return whether there are services found
70 public boolean hasServices();
73 * Check if service discovery is still in progress. List of operations may be
74 * incomplete when the discoverer is running.
76 * @return whether the discoverer is running
78 public boolean isRunning();
81 * Check if the discoverer is done searching for services. List of operations
82 * should be complete if this methods returns true.
84 * @return whether the discoverer finished
86 public boolean isDone();
89 * Start the service discovery and return a future which will be set with this
90 * discoverer when the process is completed. This method should be called once
91 * on startup and then every time the urls list is updated.
93 * @return future that will be set on discovery completion
95 public CompletableFuture<WebServiceDiscovererI> startDiscoverer();
98 * Get the error messages that occurred during service discovery.
100 * @return error message
102 public String getErrorMessages();
105 * An interface for the listeners observing the changes to the operations
111 static interface OperationsChangeListener
114 * Called whenever the operations list of the observed discoverer changes
115 * with that discoverer as the first argument and current operations list as
116 * the second. Operations list can be empty if there are no services or the
117 * list was cleared at the beginning of the discovery.
122 public void operationsChanged(WebServiceDiscovererI discoverer,
123 List<Operation> operations);
126 List<OperationsChangeListener> serviceListeners = new CopyOnWriteArrayList<>();
129 * Add an operations list observer that will be notified of any changes.
132 * operations list listener
134 public default void addOperationsChangeListener(
135 OperationsChangeListener listener)
137 serviceListeners.add(listener);
141 * Remove the listener from the observers list.
144 * listener to be removed
146 public default void removeOperationsChangeListener(
147 OperationsChangeListener listener)
149 serviceListeners.remove(listener);
153 * Called whenever the list of operations changes. Notifies all listeners of
154 * the change to the operations list. Typically, should be called with an
155 * empty list at the beginning of the service discovery process and for the
156 * second time with the list of discovered operations after that.
159 * new list of discovered operations
161 default void fireOperationsChanged(List<Operation> list)
163 for (var listener : serviceListeners)
165 listener.operationsChanged(this, list);