org.osgi.util.tracker

Class ServiceTracker<S,T>

java.lang.Object

org.osgi.util.tracker.ServiceTracker<S,T>

Type Parameters:

S - The type of the service being tracked.

T - The type of the tracked object.

All Implemented Interfaces:

ServiceTrackerCustomizer<S,T>

public class ServiceTracker<S,T>
extends java.lang.Object
implements ServiceTrackerCustomizer<S,T>

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 can use a ServiceTrackerCustomizer to customize the service objects to be tracked. The ServiceTracker can then be opened to begin tracking all services in the Framework's service registry that match the specified search criteria. The ServiceTracker correctly handles all of the details of listening to ServiceEvents 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 while holding any locks. ServiceTrackerCustomizer implementations must also be thread-safe.

Author:

$Id: a0af979aa9c88a89f220c1b2d8d7c060ced41006 $

ThreadSafe

Field Summary

Fields

Modifier and Type	Field and Description
protected BundleContext	context The Bundle Context used by this ServiceTracker.
protected Filter	filter The Filter used by this ServiceTracker which specifies the search criteria for the services to track.

Constructor Summary

Constructors

Constructor and Description
ServiceTracker(BundleContext context, java.lang.Class<S> clazz, ServiceTrackerCustomizer<S,T> customizer) Create a ServiceTracker on the specified class.
ServiceTracker(BundleContext context, Filter filter, ServiceTrackerCustomizer<S,T> customizer) Create a ServiceTracker on the specified Filter object.
ServiceTracker(BundleContext context, ServiceReference<S> reference, ServiceTrackerCustomizer<S,T> customizer) Create a ServiceTracker on the specified ServiceReference .
ServiceTracker(BundleContext context, java.lang.String clazz, ServiceTrackerCustomizer<S,T> customizer) Create a ServiceTracker on the specified class name.

Method Summary

Methods

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

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

The Bundle Context used by this ServiceTracker.

filter

protected final Filter filter

The Filter used by this ServiceTracker which specifies the search criteria for the services to track.

Since:

1.1

Constructor Detail

ServiceTracker

public ServiceTracker(BundleContext context,
              ServiceReference<S> reference,
              ServiceTrackerCustomizer<S,T> customizer)

Create a ServiceTracker on the specified ServiceReference .

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

Parameters:

context - The BundleContext against which the tracking is done.

reference - The ServiceReference for the service to be tracked.

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

ServiceTracker

public ServiceTracker(BundleContext context,
              java.lang.String clazz,
              ServiceTrackerCustomizer<S,T> customizer)

Create a ServiceTracker on the specified class name.

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

Parameters:

context - The BundleContext against which the tracking is done.

clazz - The class name of the services to be tracked.

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

ServiceTracker

public ServiceTracker(BundleContext context,
              Filter filter,
              ServiceTrackerCustomizer<S,T> customizer)

Create a ServiceTracker on the specified Filter object.

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

Parameters:

context - The BundleContext against which the tracking is done.

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

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

Since:

1.1

ServiceTracker

public ServiceTracker(BundleContext context,
              java.lang.Class<S> clazz,
              ServiceTrackerCustomizer<S,T> customizer)

Create a ServiceTracker on the specified class.

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

Parameters:

context - The BundleContext against which the tracking is done.

clazz - The class of the services to be tracked.

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

Since:

1.5

Method Detail

open

public void open()

Open this ServiceTracker and begin tracking services.

This implementation calls open(false).

Throws:

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

See Also:

open(boolean)

open

public void open(boolean trackAllServices)

Open this ServiceTracker and begin tracking services.

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

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 accessible to the bundle whose BundleContext is used by this ServiceTracker.

Throws:

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

Since:

1.3

close

public void close()

Close this ServiceTracker.

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

This implementation calls getServiceReferences() to get the list of tracked services to remove.

addingService

public T addingService(ServiceReference<S> reference)

Default implementation of the ServiceTrackerCustomizer.addingService method.

This method is only called when this ServiceTracker has been constructed with a null ServiceTrackerCustomizer argument.

This implementation returns the result of calling getService on the BundleContext with which this ServiceTracker was created passing the specified ServiceReference.

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 to unget the service.

Specified by:

addingService in interface ServiceTrackerCustomizer<S,T>

Parameters:

reference - The reference to the service being added to this ServiceTracker.

Returns:

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

See Also:

ServiceTrackerCustomizer.addingService(ServiceReference)

modifiedService

public void modifiedService(ServiceReference<S> reference,
                   T service)

Default implementation of the ServiceTrackerCustomizer.modifiedService method.

This method is only called when this ServiceTracker has been constructed with a null ServiceTrackerCustomizer argument.

This implementation does nothing.

Specified by:

modifiedService in interface ServiceTrackerCustomizer<S,T>

Parameters:

reference - The reference to modified service.

service - The service object for the modified service.

See Also:

ServiceTrackerCustomizer.modifiedService(ServiceReference, Object)

removedService

public void removedService(ServiceReference<S> reference,
                  T service)

Default implementation of the ServiceTrackerCustomizer.removedService method.

This method is only called when this ServiceTracker has been constructed with a null ServiceTrackerCustomizer argument.

This implementation calls ungetService, on the BundleContext with which this ServiceTracker was created, passing the specified ServiceReference.

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<S,T>

Parameters:

reference - The reference to removed service.

service - The service object for the removed service.

See Also:

ServiceTrackerCustomizer.removedService(ServiceReference, Object)

waitForService

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

Wait for at least one service to be tracked by this ServiceTracker. This method will also return when this ServiceTracker is closed.

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.

This implementation calls getService() to determine if a service is being tracked.

Parameters:

timeout - The 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.

getServiceReferences

public ServiceReference<S>[] getServiceReferences()

Return an array of ServiceReferences for all services being tracked by this ServiceTracker.

Returns:

Array of ServiceReferences or null if no services are being tracked.

getServiceReference

public ServiceReference<S> getServiceReference()

Returns a ServiceReference for one of the services being tracked by this ServiceTracker.

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.

This implementation calls getServiceReferences() to get the list of references for the tracked services.

Returns:

A ServiceReference or null if no services are being tracked.

Since:

1.1

getService

public T getService(ServiceReference<S> reference)

Returns the service object for the specified ServiceReference if the specified referenced service is being tracked by this ServiceTracker.

Parameters:

reference - The reference to the desired service.

Returns:

A service object or null if the service referenced by the specified ServiceReference is not being tracked.

getServices

public java.lang.Object[] getServices()

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

This implementation calls getServiceReferences() to get the list of references for the tracked services and then calls getService(ServiceReference) for each reference to get the tracked service object.

Returns:

An array of service objects or null if no services are being tracked.

getService

public T getService()

Returns a service object for one of the services being tracked by this ServiceTracker.

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

Returns:

A service object or null if no services are being tracked.

remove

public void remove(ServiceReference<S> reference)

Remove a service from this ServiceTracker. The specified service will be removed from this ServiceTracker. If the specified service was being tracked then the ServiceTrackerCustomizer.removedService method will be called for that service.

Parameters:

reference - The reference to the service to be removed.

size

public int size()

Return the number of services being tracked by this ServiceTracker.

Returns:

The number of services being tracked.

getTrackingCount

public int getTrackingCount()

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

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

Returns:

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

Since:

1.2

getTracked

public java.util.SortedMap<ServiceReference<S>,T> getTracked()

Return a SortedMap of the ServiceReferences and service objects for all services being tracked by this ServiceTracker. The map is sorted in reverse natural order of ServiceReference. That is, the first entry is the service with the highest ranking and the lowest service id.

Returns:

A SortedMap with the ServiceReferences and service objects for all services being tracked by this ServiceTracker. If no services are being tracked, then the returned map is empty.

Since:

1.5

isEmpty

public boolean isEmpty()

Return if this ServiceTracker is empty.

Returns:

true if this ServiceTracker is not tracking any services.

Since:

1.5

getServices

public T[] getServices(T[] array)

Return an array of service objects for all services being tracked by this ServiceTracker. The runtime type of the returned array is that of the specified array.

This implementation calls getServiceReferences() to get the list of references for the tracked services and then calls getService(ServiceReference) for each reference to get the tracked service object.

Parameters:

array - An array into which the tracked service objects will be stored, if the array is large enough.

Returns:

An array of service objects being tracked. If the specified array is large enough to hold the result, then the specified array is returned. If the specified array is longer then necessary to hold the result, the array element after the last service object is set to null. If the specified array is not large enough to hold the result, a new array is created and returned.

Since:

1.5