Package org.eclipse.ecf.discovery

# Interface IDiscoveryLocator

All Superinterfaces:
  `org.eclipse.core.runtime.IAdaptable`

All Known Subinterfaces:
  `IDiscoveryContainerAdapter`, `IDiscoveryService`

All Known Implementing Classes:
  `AbstractDiscoveryContainerAdapter`, `DnsSdDiscoveryAdvertiser`, `DnsSdDiscoveryContainerAdapter`, `DnsSdDiscoveryLocator`, `JSLPDiscoveryContainer`

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

Fields
Modifier and Type
Field
Description
`static final String`
`CONTAINER_NAME`
The name of the discovery container under which it is registered with the OSGi runtime as a service property

## Method Summary

Modifier and Type
Method
Description
`void`
`addServiceListener(IServiceTypeID type, IServiceListener listener)`
Add a service listener.
`void`
`addServiceListener(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(IServiceTypeID type, IServiceListener listener)`
Remove a service listener.
`void`
`removeServiceListener(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 Details

### CONTAINER_NAME

static final 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 Details

### getServiceInfo

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

Parameters:
  `aServiceID` - 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:
  `aServiceTypeID` - 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:
  `aServiceID` - 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:
  `aServiceTypeID` - 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.