BundleTracker
Date: 2016-06-24

org.osgi.util.tracker

## Class BundleTracker<T>

- java.lang.Object
- - org.osgi.util.tracker.BundleTracker<T>

- Type Parameters:
    `T` - The type of the tracked object.
  All Implemented Interfaces:
    BundleTrackerCustomizer<T>

      public class BundleTracker<T>
      extends java.lang.Object
      implements BundleTrackerCustomizer<T>

  The `BundleTracker` class simplifies tracking bundles much like the `ServiceTracker` simplifies tracking services.

  A `BundleTracker` is constructed with state criteria and a `BundleTrackerCustomizer` object. A `BundleTracker` can use the `BundleTrackerCustomizer` to select which bundles are tracked and to create a customized object to be tracked with the bundle. The `BundleTracker` can then be opened to begin tracking all bundles whose state matches the specified state criteria.

  The `getBundles` method can be called to get the `Bundle` objects of the bundles being tracked. The `getObject` method can be called to get the customized object for a tracked bundle.

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

  Since:
    1.4

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected BundleContext` | `context` The Bundle Context used by this `BundleTracker`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BundleTracker(BundleContext context, int stateMask, BundleTrackerCustomizer<T> customizer)` Create a `BundleTracker` for bundles whose state is present in the specified state mask.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `addingBundle(Bundle bundle, BundleEvent event)` Default implementation of the `BundleTrackerCustomizer.addingBundle` method.
    `void` | `close()` Close this `BundleTracker`.
    `Bundle[]` | `getBundles()` Return an array of `Bundle`s for all bundles being tracked by this `BundleTracker`.
    `T` | `getObject(Bundle bundle)` Returns the customized object for the specified `Bundle` if the specified bundle is being tracked by this `BundleTracker`.
    `java.util.Map<Bundle,T>` | `getTracked()` Return a `Map` with the `Bundle`s and customized objects for all bundles being tracked by this `BundleTracker`.
    `int` | `getTrackingCount()` Returns the tracking count for this `BundleTracker`.
    `boolean` | `isEmpty()` Return if this `BundleTracker` is empty.
    `void` | `modifiedBundle(Bundle bundle, BundleEvent event, T object)` Default implementation of the `BundleTrackerCustomizer.modifiedBundle` method.
    `void` | `open()` Open this `BundleTracker` and begin tracking bundles.
    `void` | `remove(Bundle bundle)` Remove a bundle from this `BundleTracker`.
    `void` | `removedBundle(Bundle bundle, BundleEvent event, T object)` Default implementation of the `BundleTrackerCustomizer.removedBundle` method.
    `int` | `size()` Return the number of bundles being tracked by this `BundleTracker`.

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

  - ### Constructor Detail

    - #### BundleTracker

          public BundleTracker(BundleContext context,
                       int stateMask,
                       BundleTrackerCustomizer<T> customizer)

      Create a `BundleTracker` for bundles whose state is present in the specified state mask.

      Bundles whose state is present on the specified state mask will be tracked by this `BundleTracker`.

      Parameters:
        `context` - The `BundleContext` against which the tracking is done.
        `stateMask` - The bit mask of the `OR`ing of the bundle states to be tracked.
        `customizer` - The customizer object to call when bundles are added, modified, or removed in this `BundleTracker`. If customizer is `null`, then this `BundleTracker` will be used as the `BundleTrackerCustomizer` and this `BundleTracker` will call the `BundleTrackerCustomizer` methods on itself.
      See Also:
        `Bundle.getState()`

  - ### Method Detail

    - #### open

          public void open()

      Open this `BundleTracker` and begin tracking bundles.

      Bundle which match the state criteria specified when this `BundleTracker` was created are now tracked by this `BundleTracker`.

      Throws:
        `java.lang.IllegalStateException` - If the `BundleContext` with which this `BundleTracker` was created is no longer valid.
        `java.lang.SecurityException` - If the caller and this class do not have the appropriate `AdminPermission[context bundle,LISTENER]`, and the Java Runtime Environment supports permissions.

    - #### close

          public void close()

      Close this `BundleTracker`.

      This method should be called when this `BundleTracker` should end the tracking of bundles.

      This implementation calls `getBundles()` to get the list of tracked bundles to remove.

    - #### addingBundle

          public T addingBundle(Bundle bundle,
                       BundleEvent event)

      Default implementation of the `BundleTrackerCustomizer.addingBundle` method.

      This method is only called when this `BundleTracker` has been constructed with a `null BundleTrackerCustomizer` argument.

      This implementation simply returns the specified `Bundle`.

      This method can be overridden in a subclass to customize the object to be tracked for the bundle being added.

      Specified by:
        `addingBundle` in interface `BundleTrackerCustomizer<T>`
      Parameters:
        `bundle` - The `Bundle` being added to this `BundleTracker` object.
        `event` - The bundle event which caused this customizer method to be called or `null` if there is no bundle event associated with the call to this method.
      Returns:
        The specified bundle.
      See Also:
        `BundleTrackerCustomizer.addingBundle(Bundle, BundleEvent)`

    - #### modifiedBundle

          public void modifiedBundle(Bundle bundle,
                            BundleEvent event,
                            T object)

      Default implementation of the `BundleTrackerCustomizer.modifiedBundle` method.

      This method is only called when this `BundleTracker` has been constructed with a `null BundleTrackerCustomizer` argument.

      This implementation does nothing.

      Specified by:
        `modifiedBundle` in interface `BundleTrackerCustomizer<T>`
      Parameters:
        `bundle` - The `Bundle` whose state has been modified.
        `event` - The bundle event which caused this customizer method to be called or `null` if there is no bundle event associated with the call to this method.
        `object` - The customized object for the specified Bundle.
      See Also:
        `BundleTrackerCustomizer.modifiedBundle(Bundle, BundleEvent, Object)`

    - #### removedBundle

          public void removedBundle(Bundle bundle,
                           BundleEvent event,
                           T object)

      Default implementation of the `BundleTrackerCustomizer.removedBundle` method.

      This method is only called when this `BundleTracker` has been constructed with a `null BundleTrackerCustomizer` argument.

      This implementation does nothing.

      Specified by:
        `removedBundle` in interface `BundleTrackerCustomizer<T>`
      Parameters:
        `bundle` - The `Bundle` being removed.
        `event` - The bundle event which caused this customizer method to be called or `null` if there is no bundle event associated with the call to this method.
        `object` - The customized object for the specified bundle.
      See Also:
        `BundleTrackerCustomizer.removedBundle(Bundle, BundleEvent, Object)`

    - #### getBundles

          public Bundle[] getBundles()

      Return an array of `Bundle`s for all bundles being tracked by this `BundleTracker`.
      Returns:
        An array of `Bundle`s or `null` if no bundles are being tracked.

    - #### getObject

          public T getObject(Bundle bundle)

      Returns the customized object for the specified `Bundle` if the specified bundle is being tracked by this `BundleTracker`.
      Parameters:
        `bundle` - The `Bundle` being tracked.
      Returns:
        The customized object for the specified `Bundle` or `null` if the specified `Bundle` is not being tracked.

    - #### remove

          public void remove(Bundle bundle)

      Remove a bundle from this `BundleTracker`. The specified bundle will be removed from this `BundleTracker` . If the specified bundle was being tracked then the `BundleTrackerCustomizer.removedBundle` method will be called for that bundle.
      Parameters:
        `bundle` - The `Bundle` to be removed.

    - #### size

          public int size()

      Return the number of bundles being tracked by this `BundleTracker`.
      Returns:
        The number of bundles being tracked.

    - #### getTrackingCount

          public int getTrackingCount()

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

      The tracking count can be used to determine if this `BundleTracker` has added, modified or removed a bundle by comparing a tracking count value previously collected with the current tracking count value. If the value has not changed, then no bundle has been added, modified or removed from this `BundleTracker` since the previous tracking count was collected.

      Returns:
        The tracking count for this `BundleTracker` or -1 if this `BundleTracker` is not open.

    - #### getTracked

          public java.util.Map<Bundle,T> getTracked()

      Return a `Map` with the `Bundle`s and customized objects for all bundles being tracked by this `BundleTracker`.
      Returns:
        A `Map` with the `Bundle`s and customized objects for all services being tracked by this `BundleTracker`. If no bundles are being tracked, then the returned map is empty.
      Since:
        1.5

    - #### isEmpty

          public boolean isEmpty()

      Return if this `BundleTracker` is empty.
      Returns:
        `true` if this `BundleTracker` is not tracking any bundles.
      Since:
        1.5