ServiceTrackerCustomizer
Date: 2016-06-24

org.osgi.util.tracker

## Interface ServiceTrackerCustomizer<S,T>

- Type Parameters:
    `S` - The type of the service being tracked.
    `T` - The type of the tracked object.
  All Known Implementing Classes:
    ServiceTracker

      @ConsumerType
      public interface ServiceTrackerCustomizer<S,T>

  The `ServiceTrackerCustomizer` interface allows a `ServiceTracker` to customize the service objects that are tracked. A `ServiceTrackerCustomizer` is called when a service is being added to a `ServiceTracker`. The `ServiceTrackerCustomizer` can then return an object for the tracked service. A `ServiceTrackerCustomizer` is also called when a tracked service is modified or has been removed from a `ServiceTracker`.

  The methods in this interface may be called as the result of a `ServiceEvent` being received by a `ServiceTracker`. Since `ServiceEvent`s are synchronously delivered by the Framework, it is highly recommended that implementations of these methods do not register ( `BundleContext.registerService`), modify ( `ServiceRegistration.setProperties`) or unregister ( `ServiceRegistration.unregister`) a service while being synchronized on any object.

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

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `addingService(ServiceReference<S> reference)` A service is being added to the `ServiceTracker`.
    `void` | `modifiedService(ServiceReference<S> reference, T service)` A service tracked by the `ServiceTracker` has been modified.
    `void` | `removedService(ServiceReference<S> reference, T service)` A service tracked by the `ServiceTracker` has been removed.

- - ### Method Detail

    - #### addingService

          T addingService(ServiceReference<S> reference)

      A service is being added to the `ServiceTracker`.

      This method is called before a service which matched the search parameters of the `ServiceTracker` is added to the `ServiceTracker`. This method should return the service object to be tracked for the specified `ServiceReference`. The returned service object is stored in the `ServiceTracker` and is available from the `getService` and `getServices` methods.

      Parameters:
        `reference` - The reference to the service being added to the `ServiceTracker`.
      Returns:
        The service object to be tracked for the specified referenced service or `null` if the specified referenced service should not be tracked.

    - #### modifiedService

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

      A service tracked by the `ServiceTracker` has been modified.

      This method is called when a service being tracked by the `ServiceTracker` has had it properties modified.

      Parameters:
        `reference` - The reference to the service that has been modified.
        `service` - The service object for the specified referenced service.

    - #### removedService

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

      A service tracked by the `ServiceTracker` has been removed.

      This method is called after a service is no longer being tracked by the `ServiceTracker`.

      Parameters:
        `reference` - The reference to the service that has been removed.
        `service` - The service object for the specified referenced service.