Top Description Inners Fields Constructors Methods
org.osgi.util.tracker

public Class BundleTracker<T>

extends Object
implements BundleTrackerCustomizer<T>
Class Inheritance
All Implemented Interfaces
org.osgi.util.tracker.BundleTrackerCustomizer
Annotations
@ConsumerType
Type Parameters
<T>
The type of the tracked object.
Imports
java.util.HashMap, .Map, org.osgi.annotation.versioning.ConsumerType, org.osgi.framework.Bundle, .BundleContext, .BundleEvent, .SynchronousBundleListener
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.

Author
$Id: 3682b0c1b257ec7c6760e9c4e5d62a3eda567451 $
Since
1.4

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
BundleTracker.Tracked

Inner class which subclasses AbstractTracked.

Field Summary

Modifier and TypeField and Description
protected final BundleContext
context

The Bundle Context used by this BundleTracker.

pack-priv final BundleTrackerCustomizer<T>
customizer

The BundleTrackerCustomizer object for this tracker.

pack-priv static final boolean
DEBUG

pack-priv final int
mask

State mask for bundles being tracked.

private volatile BundleTracker<T>.Tracked
tracked

Tracked bundles: Bundle object -> customized Object and BundleListener object

Constructor Summary

AccessConstructor and Description
public
BundleTracker(BundleContext
The BundleContext against which the tracking is done.
context, int
The bit mask of the ORing of the bundle states to be tracked.
stateMask, BundleTrackerCustomizer<T>
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.
customizer)

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

Method Summary

Modifier and TypeMethod and Description
public T

Returns:

The specified bundle.
addingBundle(Bundle
The Bundle being added to this BundleTracker object.
bundle, BundleEvent
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.
event)

Implements org.osgi.util.tracker.BundleTrackerCustomizer.addingBundle.

Default implementation of the BundleTrackerCustomizer.addingBundle method.

public void
close()

Close this BundleTracker.

public Bundle[]

Returns:

An array of Bundles or null if no bundles are being tracked.
getBundles()

Return an array of Bundles for all bundles being tracked by this BundleTracker.

public T

Returns:

The customized object for the specified Bundle or null if the specified Bundle is not being tracked.
getObject(Bundle
The Bundle being tracked.
bundle)

Returns the customized object for the specified Bundle if the specified bundle is being tracked by this BundleTracker.

public Map<Bundle, T>

Returns:

A Map with the Bundles and customized objects for all services being tracked by this BundleTracker. If no bundles are being tracked, then the returned map is empty.
getTracked()

Return a Map with the Bundles and customized objects for all bundles being tracked by this BundleTracker.

public int

Returns:

The tracking count for this BundleTracker or -1 if this BundleTracker is not open.
getTrackingCount()

Returns the tracking count for this BundleTracker.

public boolean

Returns:

true if this BundleTracker is not tracking any bundles.
isEmpty()

Return if this BundleTracker is empty.

public void
modifiedBundle(Bundle
The Bundle whose state has been modified.
bundle, BundleEvent
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.
event, T
The customized object for the specified Bundle.
object)

Implements org.osgi.util.tracker.BundleTrackerCustomizer.modifiedBundle.

Default implementation of the BundleTrackerCustomizer.modifiedBundle method.

public void
open()

Open this BundleTracker and begin tracking bundles.

public void
remove(Bundle
The Bundle to be removed.
bundle)

Remove a bundle from this BundleTracker.

public void
removedBundle(Bundle
The Bundle being removed.
bundle, BundleEvent
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.
event, T
The customized object for the specified bundle.
object)

Implements org.osgi.util.tracker.BundleTrackerCustomizer.removedBundle.

Default implementation of the BundleTrackerCustomizer.removedBundle method.

public int

Returns:

The number of bundles being tracked.
size()

Return the number of bundles being tracked by this BundleTracker.

private BundleTracker<T>.Tracked

Returns:

The current Tracked object.
tracked()

Accessor method for the current Tracked object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

contextback to summary
protected final BundleContext context

The Bundle Context used by this BundleTracker.

customizerback to summary
pack-priv final BundleTrackerCustomizer<T> customizer

The BundleTrackerCustomizer object for this tracker.

DEBUGback to summary
pack-priv static final boolean DEBUG
maskback to summary
pack-priv final int mask

State mask for bundles being tracked. This field contains the ORed values of the bundle states being tracked.

trackedback to summary
private volatile BundleTracker<T>.Tracked tracked

Tracked bundles: Bundle object -> customized Object and BundleListener object

Constructor Detail

BundleTrackerback to summary
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:BundleContext

The BundleContext against which the tracking is done.

stateMask:int

The bit mask of the ORing of the bundle states to be tracked.

customizer:BundleTrackerCustomizer<T>

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

addingBundleback to summary
public T addingBundle(Bundle bundle, BundleEvent event)

Implements org.osgi.util.tracker.BundleTrackerCustomizer.addingBundle.

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.

Parameters
bundle:Bundle

The Bundle being added to this BundleTracker object.

event:BundleEvent

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:T

The specified bundle.

Annotations
@Override
See Also
BundleTrackerCustomizer#addingBundle(Bundle, BundleEvent)
closeback to summary
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.

getBundlesback to summary
public Bundle[] getBundles()

Return an array of Bundles for all bundles being tracked by this BundleTracker.

Returns:Bundle[]

An array of Bundles or null if no bundles are being tracked.

getObjectback to summary
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:Bundle

The Bundle being tracked.

Returns:T

The customized object for the specified Bundle or null if the specified Bundle is not being tracked.

getTrackedback to summary
public Map<Bundle, T> getTracked()

Return a Map with the Bundles and customized objects for all bundles being tracked by this BundleTracker.

Returns:Map<Bundle, T>

A Map with the Bundles 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
getTrackingCountback to summary
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:int

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

isEmptyback to summary
public boolean isEmpty()

Return if this BundleTracker is empty.

Returns:boolean

true if this BundleTracker is not tracking any bundles.

Since
1.5
modifiedBundleback to summary
public void modifiedBundle(Bundle bundle, BundleEvent event, T object)

Implements org.osgi.util.tracker.BundleTrackerCustomizer.modifiedBundle.

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.

Parameters
bundle:Bundle

The Bundle whose state has been modified.

event:BundleEvent

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:T

The customized object for the specified Bundle.

Annotations
@Override
See Also
BundleTrackerCustomizer#modifiedBundle(Bundle, BundleEvent, Object)
openback to summary
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.

Exceptions
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.
removeback to summary
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:Bundle

The Bundle to be removed.

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

Implements org.osgi.util.tracker.BundleTrackerCustomizer.removedBundle.

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.

Parameters
bundle:Bundle

The Bundle being removed.

event:BundleEvent

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:T

The customized object for the specified bundle.

Annotations
@Override
See Also
BundleTrackerCustomizer#removedBundle(Bundle, BundleEvent, Object)
sizeback to summary
public int size()

Return the number of bundles being tracked by this BundleTracker.

Returns:int

The number of bundles being tracked.

trackedback to summary
private BundleTracker<T>.Tracked tracked()

Accessor method for the current Tracked object. This method is only intended to be used by the unsynchronized methods which do not modify the tracked field.

Returns:BundleTracker<T>.Tracked

The current Tracked object.

org.osgi.util.tracker back to summary

private final Class BundleTracker.Tracked

extends AbstractTracked<Bundle, T, BundleEvent>
implements SynchronousBundleListener
Class Inheritance
All Implemented Interfaces
org.osgi.framework.SynchronousBundleListener, org.osgi.framework.BundleListener, java.util.EventListener
Inner class which subclasses AbstractTracked. This class is the SynchronousBundleListener object for the tracker.
Since
1.4

Field Summary

Inherited from org.osgi.util.tracker.AbstractTracked:
closedDEBUG

Constructor Summary

AccessConstructor and Description
pack-priv
Tracked()

Tracked constructor.

Method Summary

Modifier and TypeMethod and Description
public void
bundleChanged(final BundleEvent
BundleEvent object from the framework.
event)

Implements org.osgi.framework.BundleListener.bundleChanged.

BundleListener method for the BundleTracker class.

pack-priv T

Returns:

Customized object for the tracked item or null if the item is not to be tracked.
customizerAdding(final Bundle
Item to be tracked.
item, final BundleEvent
Action related object.
related)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerAdding.

Call the specific customizer adding method.

pack-priv void
customizerModified(final Bundle
Tracked item.
item, final BundleEvent
Action related object.
related, final T
Customized object for the tracked item.
object)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerModified.

Call the specific customizer modified method.

pack-priv void
customizerRemoved(final Bundle
Tracked item.
item, final BundleEvent
Action related object.
related, final T
Customized object for the tracked item.
object)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerRemoved.

Call the specific customizer removed method.

Inherited from org.osgi.util.tracker.AbstractTracked:
closecopyEntriescopyKeysgetCustomizedObjectgetTrackingCountisEmptymodifiedsetInitialsizetracktrackInitialuntrack

Constructor Detail

Trackedback to summary
pack-priv Tracked()

Tracked constructor.

Method Detail

bundleChangedback to summary
public void bundleChanged(final BundleEvent event)

Implements org.osgi.framework.BundleListener.bundleChanged.

BundleListener method for the BundleTracker class. This method must NOT be synchronized to avoid deadlock potential.

Parameters
event:BundleEvent

BundleEvent object from the framework.

Annotations
@Override
customizerAddingback to summary
pack-priv T customizerAdding(final Bundle item, final BundleEvent related)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerAdding.

Call the specific customizer adding method. This method must not be called while synchronized on this object.

Parameters
item:Bundle

Item to be tracked.

related:BundleEvent

Action related object.

Returns:T

Customized object for the tracked item or null if the item is not to be tracked.

Annotations
@Override
customizerModifiedback to summary
pack-priv void customizerModified(final Bundle item, final BundleEvent related, final T object)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerModified.

Call the specific customizer modified method. This method must not be called while synchronized on this object.

Parameters
item:Bundle

Tracked item.

related:BundleEvent

Action related object.

object:T

Customized object for the tracked item.

Annotations
@Override
customizerRemovedback to summary
pack-priv void customizerRemoved(final Bundle item, final BundleEvent related, final T object)

Implements abstract org.osgi.util.tracker.AbstractTracked.customizerRemoved.

Call the specific customizer removed method. This method must not be called while synchronized on this object.

Parameters
item:Bundle

Tracked item.

related:BundleEvent

Action related object.

object:T

Customized object for the tracked item.

Annotations
@Override