Package org.eclipse.ecf.remoteservice.util.tracker

# Class RemoteServiceTracker

java.lang.Object
org.eclipse.ecf.remoteservice.util.tracker.RemoteServiceTracker

All Implemented Interfaces:
  `IRemoteServiceTrackerCustomizer`

public class RemoteServiceTracker extends Object implements IRemoteServiceTrackerCustomizer
Remote service tracker. Implementation of ServiceTracker for the ECF remoteservices API. The getRemoteService() method returns instances of `IRemoteService`.

Since:
  3.0

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final IRemoteServiceContainerAdapter`
`containerAdapter`
IRemoteServiceContainerAdapter containerAdapter against which this `RemoteServiceTracker` is tracking.
`protected final ID[]`
`containerIDs`
Container IDs that provide the context for tracking.
`protected final IRemoteFilter`
`filter`
Filter specifying search criteria for the services to track.

## Constructor Summary

Constructors
Constructor
Description
`RemoteServiceTracker(IRemoteServiceContainerAdapter containerAdapter, ID[] containerIDs, String clazz, IRemoteServiceTrackerCustomizer customizer)`
Create a `RemoteServiceTracker` object on the specified class name.
`RemoteServiceTracker(IRemoteServiceContainerAdapter containerAdapter, ID[] containerIDs, IRemoteServiceReference reference, IRemoteServiceTrackerCustomizer customizer)`
Create a `RemoteServiceTracker` on the specified `IRemoteServiceReference`.

## Method Summary

Modifier and Type
Method
Description
`IRemoteService`
`addingService(IRemoteServiceReference reference)`
Default implementation of the `IRemoteServiceTrackerCustomizer.addingService` method.
`void`
`close()`
Close this `RemoteServiceTracker`.
`IRemoteService`
`getRemoteService()`
Returns a service object for one of the services being tracked by this `RemoteServiceTracker` object.
`IRemoteService`
`getRemoteService(IRemoteServiceReference reference)`
Returns the service object for the specified `ServiceReference` object if the referenced service is being tracked by this `RemoteServiceTracker` object.
`IRemoteServiceReference`
`getRemoteServiceReference()`
Returns a `ServiceReference` object for one of the services being tracked by this `RemoteServiceTracker` object.
`IRemoteServiceReference[]`
`getRemoteServiceReferences()`
Return an array of `ServiceReference` objects for all services being tracked by this `RemoteServiceTracker` object.
`IRemoteService[]`
`getRemoteServices()`
Return an array of service objects for all services being tracked by this `RemoteServiceTracker` object.
`int`
`getTrackingCount()`
Returns the tracking count for this `RemoteServiceTracker` object.
`void`
`modifiedService(IRemoteServiceReference reference, IRemoteService remoteService)`
Default implementation of the `ServiceTrackerCustomizer.modifiedService` method.
`void`
`open()`
Open this `RemoteServiceTracker` object and begin tracking services.
`void`
`remove(IRemoteServiceReference reference)`
Remove a service from this `RemoteServiceTracker` object.
`void`
`removedService(IRemoteServiceReference reference, IRemoteService remoteService)`
Default implementation of the `ServiceTrackerCustomizer.removedService` method.
`int`
`size()`
Return the number of services being tracked by this `RemoteServiceTracker` object.
`IRemoteService`
`waitForRemoteService(long timeout)`
Wait for at least one service to be tracked by this `RemoteServiceTracker` object.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### containerAdapter

protected final IRemoteServiceContainerAdapter containerAdapter
IRemoteServiceContainerAdapter containerAdapter against which this `RemoteServiceTracker` is tracking.

### containerIDs

protected final ID[] containerIDs
Container IDs that provide the context for tracking.

### filter

protected final IRemoteFilter filter
Filter specifying search criteria for the services to track.

## Constructor Details

### RemoteServiceTracker

public RemoteServiceTracker(IRemoteServiceContainerAdapter containerAdapter, ID[] containerIDs, IRemoteServiceReference reference, IRemoteServiceTrackerCustomizer customizer)
Create a `RemoteServiceTracker` on the specified `IRemoteServiceReference`.

The remote service referenced by the specified `IRemoteServiceReference` object will be tracked by this `RemoteServiceTracker` object.

Parameters:
  `containerAdapter` - `IRemoteServiceContainerAdapter` against which the tracking is done.
  `containerIDs` - container IDs
  `reference` - `IRemoteServiceReference` for the remote service to be tracked.
  `customizer` - The customizer object to call when services are added, modified, or removed in this `RemoteServiceTracker` object. If customizer is `null`, then this `RemoteServiceTracker` object will be used as the `ServiceTrackerCustomizer` object and the `RemoteServiceTracker` object will call the `ServiceTrackerCustomizer` methods on itself.

### RemoteServiceTracker

public RemoteServiceTracker(IRemoteServiceContainerAdapter containerAdapter, ID[] containerIDs, String clazz, IRemoteServiceTrackerCustomizer customizer)
Create a `RemoteServiceTracker` object on the specified class name.

Services registered under the specified class name will be tracked by this `RemoteServiceTracker` object.

Parameters:
  `containerAdapter` - `BundleContext` object against which the tracking is done.
  `containerIDs` - container ids
  `clazz` - Class name of the services to be tracked.
  `customizer` - The customizer object to call when services are added, modified, or removed in this `RemoteServiceTracker` object. If customizer is `null`, then this `RemoteServiceTracker` object will be used as the `ServiceTrackerCustomizer` object and the `RemoteServiceTracker` object will call the `ServiceTrackerCustomizer` methods on itself.

## Method Details

### open

public void open()
Open this `RemoteServiceTracker` object and begin tracking services.

Services which match the search criteria specified when this `RemoteServiceTracker` object was created are now tracked by this `RemoteServiceTracker` object.

Throws:
  `IllegalStateException` - if the `BundleContext` object with which this `RemoteServiceTracker` object was created is no longer valid.
Since:
  1.3

### close

public void close()
Close this `RemoteServiceTracker`.

This method should be called when this `RemoteServiceTracker` object should end the tracking of services.

### addingService

public IRemoteService addingService(IRemoteServiceReference reference)
Default implementation of the `IRemoteServiceTrackerCustomizer.addingService` method.

This method is only called when this `RemoteServiceTracker` object has been constructed with a `null IRemoteServiceTrackerCustomizer` argument. The default implementation returns the result of calling `getService`, on the `BundleContext` object with which this `RemoteServiceTracker` object was created, passing the specified `ServiceReference` object.

This method can be overridden in a subclass to customize the service object to be tracked for the service being added. In that case, take care not to rely on the default implementation of removedService that will unget the service.

Specified by:
  `addingService` in interface `IRemoteServiceTrackerCustomizer`
Parameters:
  `reference` - Reference to service being added to this `RemoteServiceTracker` object.
Returns:
  The IRemoteService object to be tracked for the service added to this `RemoteServiceTracker` object.
See Also:
  - `IRemoteServiceTrackerCustomizer`

### modifiedService

public void modifiedService(IRemoteServiceReference reference, IRemoteService remoteService)
Default implementation of the `ServiceTrackerCustomizer.modifiedService` method.

This method is only called when this `RemoteServiceTracker` object has been constructed with a `null ServiceTrackerCustomizer` argument. The default implementation does nothing.

Specified by:
  `modifiedService` in interface `IRemoteServiceTrackerCustomizer`
Parameters:
  `reference` - Reference to modified service.
  `remoteService` - The service object for the modified service.
See Also:
  - `IRemoteServiceTrackerCustomizer`

### removedService

public void removedService(IRemoteServiceReference reference, IRemoteService remoteService)
Default implementation of the `ServiceTrackerCustomizer.removedService` method.

This method is only called when this `RemoteServiceTracker` object has been constructed with a `null ServiceTrackerCustomizer` argument. The default implementation calls `ungetService`, on the `BundleContext` object with which this `RemoteServiceTracker` object was created, passing the specified `ServiceReference` object.

This method can be overridden in a subclass. If the default implementation of `addingService` method was used, this method must unget the service.

Specified by:
  `removedService` in interface `IRemoteServiceTrackerCustomizer`
Parameters:
  `reference` - Reference to removed service.
  `remoteService` - The service object for the removed service.
See Also:
  - `IRemoteServiceTrackerCustomizer`

### waitForRemoteService

public IRemoteService waitForRemoteService(long timeout) throws InterruptedException
Wait for at least one service to be tracked by this `RemoteServiceTracker` object.

It is strongly recommended that `waitForService` is not used during the calling of the `BundleActivator` methods. `BundleActivator` methods are expected to complete in a short period of time.

Parameters:
  `timeout` - time interval in milliseconds to wait. If zero, the method will wait indefinitely.
Returns:
  Returns the result of `getService()`.
Throws:
  `InterruptedException` - If another thread has interrupted the current thread.
  `IllegalArgumentException` - If the value of timeout is negative.

### getRemoteServiceReferences

public IRemoteServiceReference[] getRemoteServiceReferences()
Return an array of `ServiceReference` objects for all services being tracked by this `RemoteServiceTracker` object.

Returns:
  Array of `ServiceReference` objects or `null` if no service are being tracked.

### getRemoteServiceReference

public IRemoteServiceReference getRemoteServiceReference()
Returns a `ServiceReference` object for one of the services being tracked by this `RemoteServiceTracker` object.

If multiple services are being tracked, the service with the highest ranking (as specified in its `service.ranking` property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its `service.id` property); that is, the service that was registered first is returned.

This is the same algorithm used by `BundleContext.getServiceReference`.

Returns:
  `ServiceReference` object or `null` if no service is being tracked.
Since:
  1.1

### getRemoteService

public IRemoteService getRemoteService(IRemoteServiceReference reference)
Returns the service object for the specified `ServiceReference` object if the referenced service is being tracked by this `RemoteServiceTracker` object.

Parameters:
  `reference` - Reference to the desired service.
Returns:
  Service object or `null` if the service referenced by the specified `ServiceReference` object is not being tracked.

### getRemoteServices

public IRemoteService[] getRemoteServices()
Return an array of service objects for all services being tracked by this `RemoteServiceTracker` object.

Returns:
  Array of service objects or `null` if no service are being tracked.

### getRemoteService

public IRemoteService getRemoteService()
Returns a service object for one of the services being tracked by this `RemoteServiceTracker` object.

If any services are being tracked, this method returns the result of calling `getService(getServiceReference())`.

Returns:
  Service object or `null` if no service is being tracked.

### remove

public void remove(IRemoteServiceReference reference)
Remove a service from this `RemoteServiceTracker` object. The specified service will be removed from this `RemoteServiceTracker` object. If the specified service was being tracked then the `ServiceTrackerCustomizer.removedService` method will be called for that service.

Parameters:
  `reference` - Reference to the service to be removed.

### size

public int size()
Return the number of services being tracked by this `RemoteServiceTracker` object.

Returns:
  Number of services being tracked.

### getTrackingCount

public int getTrackingCount()
Returns the tracking count for this `RemoteServiceTracker` object. The tracking count is initialized to 0 when this `RemoteServiceTracker` object is opened. Every time a service is added, modified or removed from this `RemoteServiceTracker` object the tracking count is incremented.

The tracking count can be used to determine if this `RemoteServiceTracker` object has added, modified or removed a service by comparing a tracking count value previously collected with the current tracking count value. If the value has not changed, then no service has been added, modified or removed from this `RemoteServiceTracker` object since the previous tracking count was collected.

Returns:
  The tracking count for this `RemoteServiceTracker` object or -1 if this `RemoteServiceTracker` object is not open.
Since:
  1.2