org.eclipse.ecf.discovery
Interface IDiscoveryLocator

All Superinterfaces:
org.eclipse.core.runtime.IAdaptable
All Known Subinterfaces:
IDiscoveryContainerAdapter, IDiscoveryService
All Known Implementing Classes:
AbstractDiscoveryContainerAdapter, CompositeDiscoveryContainer, DnsSdDiscoveryAdvertiser, DnsSdDiscoveryContainerAdapter, DnsSdDiscoveryLocator, JSLPDiscoveryContainer, SingletonDiscoveryContainer, ZooDiscoveryContainer

public interface IDiscoveryLocator
extends org.eclipse.core.runtime.IAdaptable

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

Field Summary
static java.lang.String CONTAINER_NAME
          The name of the discovery container under which it is registered with the OSGi runtime as a service property
 
Method Summary
 void addServiceListener(IServiceListener listener)
          Add a service listener.
 void addServiceListener(IServiceTypeID type, IServiceListener listener)
          Add a service listener.
 void addServiceTypeListener(IServiceTypeListener listener)
          Add a service type listener.
 org.eclipse.equinox.concurrent.future.IFuture getAsyncServiceInfo(IServiceID aServiceID)
          Asynchronously retrieve info about the service
 org.eclipse.equinox.concurrent.future.IFuture getAsyncServices()
          Asynchronously get service info about all known services
 org.eclipse.equinox.concurrent.future.IFuture getAsyncServices(IServiceTypeID aServiceTypeID)
          Asynchronously get service info about all known services of given service type
 org.eclipse.equinox.concurrent.future.IFuture getAsyncServiceTypes()
          Asynchronously get service info about all known services of given service type
 IServiceInfo getServiceInfo(IServiceID aServiceID)
          Synchronously retrieve info about the service
 IServiceInfo[] getServices()
          Synchronously get service info about all known services
 IServiceInfo[] getServices(IServiceTypeID aServiceTypeID)
          Synchronously get service info about all known services of given service type
 Namespace getServicesNamespace()
          Get a Namespace for services associated with this discovery container adapter.
 IServiceTypeID[] getServiceTypes()
          Synchronously get service info about all known services of given service type
 IServiceInfo[] purgeCache()
          Purges the underlying IServiceInfo cache if available in the current provider
 void removeServiceListener(IServiceListener listener)
          Remove a service listener.
 void removeServiceListener(IServiceTypeID type, IServiceListener listener)
          Remove a service listener.
 void removeServiceTypeListener(IServiceTypeListener listener)
          Remove a service type listener.
 
Methods inherited from interface org.eclipse.core.runtime.IAdaptable
getAdapter
 

Field Detail

CONTAINER_NAME

static final java.lang.String CONTAINER_NAME
The name of the discovery container under which it is registered with the OSGi runtime as a service property

See Also:
Constant Field Values
Method Detail

getServiceInfo

IServiceInfo getServiceInfo(IServiceID aServiceID)
Synchronously retrieve info about the service

Parameters:
service - IServiceID of the service to get info about. Must not be null.
Returns:
IServiceInfo the service info retrieved. null if no information retrievable.

getServices

IServiceInfo[] getServices()
Synchronously get service info about all known services

Returns:
IServiceInfo[] the resulting array of service info instances. Will not be null. May be of length 0.

getServices

IServiceInfo[] getServices(IServiceTypeID aServiceTypeID)
Synchronously get service info about all known services of given service type

Parameters:
type - IServiceTypeID defining the type of service we are interested in getting service info about. Must not be null
Returns:
IServiceInfo[] the resulting array of service info instances. Will not be null. May be of length 0.

getServiceTypes

IServiceTypeID[] getServiceTypes()
Synchronously get service info about all known services of given service type

Returns:
IServiceTypeID[] the resulting array of service type IDs. Will not be null. May be of length 0.

getServicesNamespace

Namespace getServicesNamespace()
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);
 

Returns:
Namespace for creating service IDs. Will not be null .

purgeCache

IServiceInfo[] purgeCache()
Purges the underlying IServiceInfo cache if available in the current provider

Returns:
The previous cache content

addServiceListener

void addServiceListener(IServiceListener listener)
Add a service listener. The given listener will have its method called when a service is discovered.

Parameters:
listener - IServiceListener to be notified. Must not be null .

addServiceListener

void addServiceListener(IServiceTypeID type,
                        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.

Parameters:
type - String type to listen for. Must not be null. Must be formatted according to this specific IDiscoveryContainer
listener - IServiceListener to be notified. Must not be null .

addServiceTypeListener

void addServiceTypeListener(IServiceTypeListener listener)
Add a service type listener. The given listener will have its method called when a service type is discovered.

Parameters:
listener - the listener to be notified. Must not be null.

removeServiceListener

void removeServiceListener(IServiceListener listener)
Remove a service listener. Remove the listener from this container

Parameters:
listener - IServiceListener listener to be removed. Must not be null.

removeServiceListener

void removeServiceListener(IServiceTypeID type,
                           IServiceListener listener)
Remove a service listener. Remove the listener associated with the type specified by the first parameter.

Parameters:
type - String of the desired type to remove the listener. Must not be null. Must be formatted according to this specific IDiscoveryContainer
listener - IServiceListener listener to be removed. Must not be null.

removeServiceTypeListener

void removeServiceTypeListener(IServiceTypeListener listener)
Remove a service type listener. Remove the type listener.

Parameters:
listener - IServiceTypeListener to be removed. Must not be null.

getAsyncServiceInfo

org.eclipse.equinox.concurrent.future.IFuture getAsyncServiceInfo(IServiceID aServiceID)
Asynchronously retrieve info about the service

Parameters:
service - IServiceID of the service to get info about. Must not be null.
Returns:
IFuture a future status wrapping an IServiceInfo or null if no information retrievable.

getAsyncServices

org.eclipse.equinox.concurrent.future.IFuture getAsyncServices()
Asynchronously get service info about all known services

Returns:
IFuture wrapping an IServiceTypeID[]. The resulting array of service type IDs will not be null. May be of length 0.

getAsyncServices

org.eclipse.equinox.concurrent.future.IFuture getAsyncServices(IServiceTypeID aServiceTypeID)
Asynchronously get service info about all known services of given service type

Parameters:
type - IServiceTypeID defining the type of service we are interested in getting service info about. Must not be null
Returns:
IFuture wrapping an IServiceTypeID[]. The resulting array of service type IDs will not be null. May be of length 0.

getAsyncServiceTypes

org.eclipse.equinox.concurrent.future.IFuture getAsyncServiceTypes()
Asynchronously get service info about all known services of given service type

Returns:
IFuture wrapping an IServiceTypeID[]. The resulting array of service type IDs will not be null. May be of length 0.