org.eclipse.ecf.discovery.IDiscoveryLocator Maven / Gradle / Ivy
/****************************************************************************
* Copyright (c) 2009 Markus Alexander Kuppe.
*
* This program and the accompanying materials are made
* available under the terms of the Eclipse Public License 2.0
* which is available at https://www.eclipse.org/legal/epl-2.0/
*
* Contributors:
* Markus Alexander Kuppe (ecf-dev_eclipse.org lemmster de) - initial API and implementation
*
* SPDX-License-Identifier: EPL-2.0
*****************************************************************************/
package org.eclipse.ecf.discovery;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.ecf.core.identity.Namespace;
import org.eclipse.ecf.discovery.identity.IServiceID;
import org.eclipse.ecf.discovery.identity.IServiceTypeID;
import org.eclipse.equinox.concurrent.future.IFuture;
/**
* Entry point discovery locator. This interface exposes the ability to
* add/remove listeners for newly discovered services and service types, and get
* (synch) and request (asynchronous) service info from a remote service
* provider.
*
* This interface can be used by container provider implementations as an
* adapter so that calls to IContainer.getAdapter(IDiscoveryLocator.class) will
* return a non-null instance of a class that implements this interface. Clients
* can then proceed to use this interface to interact with the given discovery
* implementation.
*
* @since 3.0
*/
public interface IDiscoveryLocator extends IAdaptable {
/**
* The name of the discovery container under which it is registered with the
* OSGi runtime as a service property
*/
public static final String CONTAINER_NAME = "org.eclipse.ecf.discovery.containerName"; //$NON-NLS-1$
/**
* Synchronously retrieve info about the service
*
* @param aServiceID
* IServiceID of the service to get info about. Must not be
* null.
* @return IServiceInfo the service info retrieved. null if no
* information retrievable.
*/
public IServiceInfo getServiceInfo(IServiceID aServiceID);
/**
* Synchronously get service info about all known services
*
* @return IServiceInfo[] the resulting array of service info instances.
* Will not be null. May be of length 0.
*/
public IServiceInfo[] getServices();
/**
* Synchronously get service info about all known services of given service
* type
*
* @param aServiceTypeID
* IServiceTypeID defining the type of service we are interested
* in getting service info about. Must not be null
* @return IServiceInfo[] the resulting array of service info instances.
* Will not be null. May be of length 0.
*/
public IServiceInfo[] getServices(IServiceTypeID aServiceTypeID);
/**
* Synchronously get service info about all known services of given service
* type
*
* @return IServiceTypeID[] the resulting array of service type IDs. Will
* not be null. May be of length 0.
*/
public IServiceTypeID[] getServiceTypes();
/**
* Get a Namespace for services associated with this discovery container
* adapter. The given Namespace may be used via IServiceIDFactory to create
* IServiceIDs rather than simple IDs. For example:
*
*
* IServiceID serviceID = ServiceIDFactory.getDefault().createServiceID(container.getServicesNamespace(),
* serviceType, serviceName);
*
*
* @return Namespace for creating service IDs. Will not be null
* .
*/
public Namespace getServicesNamespace();
/**
* Purges the underlying IServiceInfo cache if available in the current
* provider
*
* @return The previous cache content
*/
public IServiceInfo[] purgeCache();
/* Listener related API */
/**
* Add a service listener. The given listener will have its method called
* when a service is discovered.
*
* @param listener
* IServiceListener to be notified. Must not be null
* .
*/
public void addServiceListener(IServiceListener listener);
/**
* Add a service listener. The given listener will have its method called
* when a service with a type matching that specified by the first parameter
* is discovered.
*
* @param type
* String type to listen for. Must not be null. Must
* be formatted according to this specific IDiscoveryContainer
* @param listener
* IServiceListener to be notified. Must not be null
* .
*/
public void addServiceListener(IServiceTypeID type, IServiceListener listener);
/**
* Add a service type listener. The given listener will have its method
* called when a service type is discovered.
*
* @param listener
* the listener to be notified. Must not be null.
*/
public void addServiceTypeListener(IServiceTypeListener listener);
/**
* Remove a service listener. Remove the listener from this container
*
* @param listener
* IServiceListener listener to be removed. Must not be
* null.
*/
public void removeServiceListener(IServiceListener listener);
/**
* Remove a service listener. Remove the listener associated with the type
* specified by the first parameter.
*
* @param type
* String of the desired type to remove the listener. Must not be
* null. Must be formatted according to this
* specific IDiscoveryContainer
* @param listener
* IServiceListener listener to be removed. Must not be
* null.
*/
public void removeServiceListener(IServiceTypeID type, IServiceListener listener);
/**
* Remove a service type listener. Remove the type listener.
*
* @param listener
* IServiceTypeListener to be removed. Must not be
* null.
*/
public void removeServiceTypeListener(IServiceTypeListener listener);
/* Future related API */
/**
* Asynchronously retrieve info about the service
*
* @param aServiceID
* IServiceID of the service to get info about. Must not be
* null.
* @return IFuture a future status wrapping an IServiceInfo or
* null if no information retrievable.
*/
public IFuture getAsyncServiceInfo(IServiceID aServiceID);
/**
* Asynchronously get service info about all known services
*
* @return IFuture wrapping an IServiceTypeID[]. The resulting array of
* service type IDs will not be null. May be of length
* 0.
*/
public IFuture getAsyncServices();
/**
* Asynchronously get service info about all known services of given service
* type
*
* @param aServiceTypeID
* IServiceTypeID defining the type of service we are interested
* in getting service info about. Must not be null
* @return IFuture wrapping an IServiceTypeID[]. The resulting array of
* service type IDs will not be null. May be of length
* 0.
*/
public IFuture getAsyncServices(IServiceTypeID aServiceTypeID);
/**
* Asynchronously get service info about all known services of given service
* type
*
* @return IFuture wrapping an IServiceTypeID[]. The resulting array of
* service type IDs will not be null. May be of length
* 0.
*/
public IFuture getAsyncServiceTypes();
}