org.osgi.util.tracker
Class ServiceTracker

java.lang.Object
  org.osgi.util.tracker.ServiceTracker

All Implemented Interfaces:

ServiceTrackerCustomizer

public class ServiceTracker

extends java.lang.Object

implements ServiceTrackerCustomizer

The ServiceTracker class simplifies using services from the Framework's service registry.

A ServiceTracker object is constructed with search criteria and a ServiceTrackerCustomizer object. A ServiceTracker object can use the ServiceTrackerCustomizer object to customize the service objects to be tracked. The ServiceTracker object can then be opened to begin tracking all services in the Framework's service registry that match the specified search criteria. The ServiceTracker object correctly handles all of the details of listening to ServiceEvent objects and getting and ungetting services.

The getServiceReferences method can be called to get references to the services being tracked. The getService and getServices methods can be called to get the service objects for the tracked service.

The ServiceTracker class is thread-safe. It does not call a ServiceTrackerCustomizer object while holding any locks. ServiceTrackerCustomizer implementations must also be thread-safe.

ThreadSafe

Field Summary

protected BundleContext	context Bundle context against which this ServiceTracker object is tracking.
protected Filter	filter Filter specifying search criteria for the services to track.

Constructor Summary

ServiceTracker(BundleContext context, Filter filter, ServiceTrackerCustomizer customizer)
Create a ServiceTracker object on the specified Filter object.

ServiceTracker(BundleContext context, ServiceReference reference, ServiceTrackerCustomizer customizer)
Create a ServiceTracker object on the specified ServiceReference object.

ServiceTracker(BundleContext context, java.lang.String clazz, ServiceTrackerCustomizer customizer)
Create a ServiceTracker object on the specified class name.

Method Summary

java.lang.Object	addingService(ServiceReference reference) Default implementation of the ServiceTrackerCustomizer.addingService method.
void	close() Close this ServiceTracker object.
java.lang.Object	getService() Returns a service object for one of the services being tracked by this ServiceTracker object.
java.lang.Object	getService(ServiceReference reference) Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this ServiceTracker object.
ServiceReference	getServiceReference() Returns a ServiceReference object for one of the services being tracked by this ServiceTracker object.
ServiceReference[]	getServiceReferences() Return an array of ServiceReference objects for all services being tracked by this ServiceTracker object.
java.lang.Object[]	getServices() Return an array of service objects for all services being tracked by this ServiceTracker object.
int	getTrackingCount() Returns the tracking count for this ServiceTracker object.
void	modifiedService(ServiceReference reference, java.lang.Object service) Default implementation of the ServiceTrackerCustomizer.modifiedService method.
void	open() Open this ServiceTracker object and begin tracking services.
void	open(boolean trackAllServices) Open this ServiceTracker object and begin tracking services.
void	remove(ServiceReference reference) Remove a service from this ServiceTracker object.
void	removedService(ServiceReference reference, java.lang.Object service) Default implementation of the ServiceTrackerCustomizer.removedService method.
int	size() Return the number of services being tracked by this ServiceTracker object.
java.lang.Object	waitForService(long timeout) Wait for at least one service to be tracked by this ServiceTracker object.

Methods inherited from class java.lang.Object

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

Field Detail

context

protected final BundleContext context

Bundle context against which this ServiceTracker object is tracking.

filter

protected final Filter filter

Filter specifying search criteria for the services to track.

Since:

1.1

Constructor Detail

ServiceTracker

public ServiceTracker(BundleContext context,
                      ServiceReference reference,
                      ServiceTrackerCustomizer customizer)

Create a ServiceTracker object on the specified ServiceReference object.

The service referenced by the specified ServiceReference object will be tracked by this ServiceTracker object.

Parameters:

context - BundleContext object against which the tracking is done.

reference - ServiceReference object for the service to be tracked.

customizer - The customizer object to call when services are added, modified, or removed in this ServiceTracker object. If customizer is null, then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself.

ServiceTracker

public ServiceTracker(BundleContext context,
                      java.lang.String clazz,
                      ServiceTrackerCustomizer customizer)

Create a ServiceTracker object on the specified class name.

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

Parameters:

context - 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 ServiceTracker object. If customizer is null, then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself.

ServiceTracker

public ServiceTracker(BundleContext context,
                      Filter filter,
                      ServiceTrackerCustomizer customizer)

Create a ServiceTracker object on the specified Filter object.

Services which match the specified Filter object will be tracked by this ServiceTracker object.

Parameters:

context - BundleContext object against which the tracking is done.

filter - Filter object to select the services to be tracked.

customizer - The customizer object to call when services are added, modified, or removed in this ServiceTracker object. If customizer is null, then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself.

Since:

1.1

Method Detail

open

public void open()

Open this ServiceTracker object and begin tracking services.

This method calls open(false).

Throws:

java.lang.IllegalStateException - if the BundleContext object with which this ServiceTracker object was created is no longer valid.

See Also:

open(boolean)

open

public void open(boolean trackAllServices)

Open this ServiceTracker object and begin tracking services.

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

Parameters:

trackAllServices - If true, then this ServiceTracker will track all matching services regardless of class loader accessibility. If false, then this ServiceTracker will only track matching services which are class loader accessibile to the bundle whose BundleContext is used by this ServiceTracker.

Throws:

java.lang.IllegalStateException - if the BundleContext object with which this ServiceTracker object was created is no longer valid.

Since:

1.3

close

public void close()

Close this ServiceTracker object.

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

addingService

public java.lang.Object addingService(ServiceReference reference)

Default implementation of the ServiceTrackerCustomizer.addingService method.

This method is only called when this ServiceTracker object has been constructed with a null ServiceTrackerCustomizer argument. The default implementation returns the result of calling getService, on the BundleContext object with which this ServiceTracker 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 ServiceTrackerCustomizer

Parameters:

reference - Reference to service being added to this ServiceTracker object.

Returns:

The service object to be tracked for the service added to this ServiceTracker object.

See Also:

ServiceTrackerCustomizer

modifiedService

public void modifiedService(ServiceReference reference,
                            java.lang.Object service)

Default implementation of the ServiceTrackerCustomizer.modifiedService method.

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

Specified by:

modifiedService in interface ServiceTrackerCustomizer

Parameters:

reference - Reference to modified service.

service - The service object for the modified service.

See Also:

ServiceTrackerCustomizer

removedService

public void removedService(ServiceReference reference,
                           java.lang.Object service)

Default implementation of the ServiceTrackerCustomizer.removedService method.

This method is only called when this ServiceTracker object has been constructed with a null ServiceTrackerCustomizer argument. The default implementation calls ungetService, on the BundleContext object with which this ServiceTracker 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 ServiceTrackerCustomizer

Parameters:

reference - Reference to removed service.

service - The service object for the removed service.

See Also:

ServiceTrackerCustomizer

waitForService

public java.lang.Object waitForService(long timeout)
                                throws java.lang.InterruptedException

Wait for at least one service to be tracked by this ServiceTracker 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 indefinately.

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.

getServiceReferences

public ServiceReference[] getServiceReferences()

Return an array of ServiceReference objects for all services being tracked by this ServiceTracker object.

Returns:

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

getServiceReference

public ServiceReference getServiceReference()

Returns a ServiceReference object for one of the services being tracked by this ServiceTracker 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

getService

public java.lang.Object getService(ServiceReference reference)

Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this ServiceTracker 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.

getServices

public java.lang.Object[] getServices()

Return an array of service objects for all services being tracked by this ServiceTracker object.

Returns:

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

getService

public java.lang.Object getService()

Returns a service object for one of the services being tracked by this ServiceTracker 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(ServiceReference reference)

Remove a service from this ServiceTracker object. The specified service will be removed from this ServiceTracker 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 ServiceTracker object.

Returns:

Number of services being tracked.

getTrackingCount

public int getTrackingCount()

Returns the tracking count for this ServiceTracker object. The tracking count is initialized to 0 when this ServiceTracker object is opened. Every time a service is added, modified or removed from this ServiceTracker object the tracking count is incremented.

The tracking count can be used to determine if this ServiceTracker 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 ServiceTracker object since the previous tracking count was collected.

Returns:

The tracking count for this ServiceTracker object or -1 if this ServiceTracker object is not open.

Since:

1.2