Package org.osgi.util.tracker

Class 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
    Author:
    $Id: 9a1b57568a8be735292700584f4eb936fc80f2ff $

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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 Bundles 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 Bundles 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 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 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 Bundles for all bundles being tracked by this BundleTracker.
        Returns:
        An array of Bundles 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 Bundles and customized objects for all bundles being tracked by this BundleTracker.
        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.
        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