Knopflerfish OSGi 1.3.3

org.osgi.util.tracker
Class ServiceTracker

java.lang.Object
  extended byorg.osgi.util.tracker.ServiceTracker
All Implemented Interfaces:
ServiceTrackerCustomizer

public class ServiceTracker
extends java.lang.Object
implements ServiceTrackerCustomizer

Utility class for grabbing services matching certain criteria.

Typical use would be:

  // Create and open a tracker for the log service
  ServiceTracker logTracker = 
         new ServiceTracker(bc, LogService.class.getname(), null);
 
  logTracker.open(); 
 
  ...

  // use the service
  ((LogService)logTracker.getService()).log(LogService.LOG_INFO, "message"));

 
Note that the above code might fail with NullPointerException if no LogService is available.


Field Summary
protected  ServiceReference bestSR
           
protected  long bestSRID
           
protected  long bestSRRank
           
protected  BundleContext context
           
protected  ServiceTrackerCustomizer customizer
           
protected  Filter filter
           
protected  ServiceListener srListener
           
protected  java.util.Hashtable tracked
           
protected  int trackingCount
           
 
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.
protected  void finalize()
          Calls the close method.
 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.
 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.
 java.lang.Object[] getServices()
          Return an array of service objects for all services being tracked.
 int getTrackingCount()
           
 void modifiedService(ServiceReference reference, java.lang.Object service)
          Default implementation of the ServiceTrackerCustomizer.modifiedService method.
 void open()
          Open this ServiceTracker 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()
          Number of services being tracked.
 java.lang.String toString()
           
protected  void updateBest(ServiceReference sr)
           
 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, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

context

protected BundleContext context

filter

protected Filter filter

customizer

protected ServiceTrackerCustomizer customizer

tracked

protected java.util.Hashtable tracked

srListener

protected ServiceListener srListener

bestSR

protected ServiceReference bestSR

bestSRRank

protected long bestSRRank

bestSRID

protected long bestSRID

trackingCount

protected int trackingCount
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.
Throws:
java.lang.IllegalArgumentException - if the class name is null, empty string or causes a InvalidSyntaxException

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

toString

public java.lang.String toString()

open

public void open()
Open this ServiceTracker and begin tracking services.

Tracking is done by adding a ServiceListener to the bundlecontext used when creating the tracker.

If the tracker is already opened, do nothing.

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

close

public void close()
Close this ServiceTracker object.

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

If the tracker is not opened, do nothing.


finalize

protected void finalize()
                 throws java.lang.Throwable
Calls the close method.

Throws:
java.lang.Throwable

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(reference).

This method can be overridden to customize the service object to be tracked for the service being added.

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.

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 modified service.

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.

Specified by:
removedService in interface ServiceTrackerCustomizer
Parameters:
reference - Reference to removed service.
service - The service object for the removed service.

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.

Don't use this method. You'll get bad karma for a long time. If you really need the functionity, you're probably much better off using a ServiceListener directly.

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

getServiceReferences

public ServiceReference[] getServiceReferences()
Return an array of ServiceReference objects for all services being tracked.

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

getServices

public java.lang.Object[] getServices()
Return an array of service objects for all services being tracked.

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

updateBest

protected void updateBest(ServiceReference sr)

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.

Implementation note: This code uses a cached best service reference for quick retrieval. The cache is rebuilt at service registration/unregistation.

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.

Parameters:
reference - Reference to a service.
Returns:
Service object or null if the service referenced by the specified ServiceReference object is not 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()
Number of services being tracked.


getTrackingCount

public int getTrackingCount()

Knopflerfish OSGi 1.3.3