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 java.lang.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

protected IRemoteServiceContainerAdapter	containerAdapter IRemoteServiceContainerAdapter containerAdapter against which this RemoteServiceTracker is tracking.
protected ID[]	containerIDs Container IDs that provide the context for tracking.
protected IRemoteFilter	filter Filter specifying search criteria for the services to track.

Constructor Summary

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

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

Method Summary

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 Detail

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 Detail

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.

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,
                            java.lang.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.

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 Detail

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:

java.lang.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 java.lang.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:

java.lang.InterruptedException - If another thread has interrupted the current thread.

java.lang.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