org.osgi.util.tracker
Class BundleTracker

java.lang.Object
  org.osgi.util.tracker.BundleTracker

All Implemented Interfaces:

BundleTrackerCustomizer

public class BundleTracker
extends java.lang.Object
implements BundleTrackerCustomizer

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

ThreadSafe

Field Summary

protected BundleContext

context The Bundle Context used by this BundleTracker.

Constructor Summary

BundleTracker(BundleContext context, int stateMask, BundleTrackerCustomizer customizer)
Create a BundleTracker for bundles whose state is present in the specified state mask.

Method Summary

java.lang.Object	addingBundle(Bundle bundle, BundleEvent event) Default implementation of the BundleTrackerCustomizer.addingBundle method.
void	close() Close this BundleTracker.
Bundle[]	getBundles() Return an array of Bundles for all bundles being tracked by this BundleTracker.
java.lang.Object	getObject(Bundle bundle) Returns the customized object for the specified Bundle if the specified bundle is being tracked by this BundleTracker.
int	getTrackingCount() Returns the tracking count for this BundleTracker.
void	modifiedBundle(Bundle bundle, BundleEvent event, java.lang.Object 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, java.lang.Object 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 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 ORing 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 java.lang.Object 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

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,
                           java.lang.Object 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

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,
                          java.lang.Object 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

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 Bundles for all bundles being tracked by this BundleTracker.

Returns:

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

getObject

public java.lang.Object 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.