ServiceTracker
Date: 2016-06-24

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 `ServiceEvent`s 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.

- - ### 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 `ServiceReference`s 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 `ServiceReference`s 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 `ServiceReference`s for all services being tracked by this `ServiceTracker`.
      Returns:
        Array of `ServiceReference`s 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 `ServiceReference`s 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 `ServiceReference`s 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