Class BundleTracker

java.lang.Object
org.osgi.util.tracker.BundleTracker
All Implemented Interfaces:
BundleTrackerCustomizer
public class BundleTracker extends 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
Version:
$Revision: 5894 $

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final org.osgi.framework.BundleContext
    context
    The Bundle Context used by this BundleTracker.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BundleTracker(org.osgi.framework.BundleContext context, int stateMask, BundleTrackerCustomizer customizer)
    Create a BundleTracker for bundles whose state is present in the specified state mask.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    addingBundle(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleEvent event)
    Default implementation of the BundleTrackerCustomizer.addingBundle method.
    void
    close()
    Close this BundleTracker.
    org.osgi.framework.Bundle[]
    getBundles()
    Return an array of Bundles for all bundles being tracked by this BundleTracker.
    Object
    getObject(org.osgi.framework.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(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleEvent event, Object object)
    Default implementation of the BundleTrackerCustomizer.modifiedBundle method.
    void
    open()
    Open this BundleTracker and begin tracking bundles.
    void
    remove(org.osgi.framework.Bundle bundle)
    Remove a bundle from this BundleTracker.
    void
    removedBundle(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleEvent event, 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 Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • context

      protected final org.osgi.framework.BundleContext context
      The Bundle Context used by this BundleTracker.

  • Constructor Details

    • BundleTracker

      public BundleTracker(org.osgi.framework.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 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 Object addingBundle(org.osgi.framework.Bundle bundle, org.osgi.framework.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:

    • modifiedBundle

      public void modifiedBundle(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleEvent event, 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:

    • removedBundle

      public void removedBundle(org.osgi.framework.Bundle bundle, org.osgi.framework.BundleEvent event, 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:

    • getBundles

      public org.osgi.framework.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 Object getObject(org.osgi.framework.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(org.osgi.framework.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.