Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Field Summary
`protected BundleContext` | `context` Bundle context this `ServiceTracker` object is tracking against.
`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` | `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 this `ServiceTracker` object is tracking against.

### 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.

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

  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.

### 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.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 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 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 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

Overview | Package | Class | Tree | Serialized | Deprecated | Index | Help
| OSGi Service Platform Release 3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) OSGi Alliance (2000, 2003). All Rights Reserved.