Package 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>`

@ConsumerType public class BundleTracker<T> extends 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
Description
`protected final BundleContext`
`context`
The Bundle Context used by this `BundleTracker`.

## Constructor Summary

Constructors
Constructor
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

Modifier and Type
Method
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`.
`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 Details

### context

protected final BundleContext context
The Bundle Context used by this `BundleTracker`.

## Constructor Details

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

### 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:
  `IllegalStateException` - If the `BundleContext` with which this `BundleTracker` was created is no longer valid.
  `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 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