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`, `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

Fields
`static String` `CONTAINER_NAME` The name of the discovery container under which it is registered with the OSGi runtime as a service property

### Method Summary

All Methods Instance Methods Abstract Methods
`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 Detail

#### 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 Detail

#### 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.