Class AbstractTracked<S,T,R>

java.lang.Object
org.osgi.util.tracker.AbstractTracked<S,T,R>
Type Parameters:
S - The tracked item. It is the key.
T - The value mapped to the tracked item.
R - The reason the tracked item is being tracked or untracked.
Direct Known Subclasses:
BundleTracker.Tracked, ServiceTracker.Tracked

abstract class AbstractTracked<S,T,R> extends Object
Abstract class to track items. If a Tracker is reused (closed then reopened), then a new AbstractTracked object is used. This class acts a map of tracked item -> customized object. Subclasses of this class will act as the listener object for the tracker. This class is used to synchronize access to the tracked items. This is not a public class. It is only for use by the implementation of the Tracker class.
Since:
1.4
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final List<S>
    List of items in the process of being added.
    (package private) boolean
    true if the tracked object is closed.
    (package private) static final boolean
     
    private final LinkedList<S>
    Initial list of items for the tracker.
    private final Map<S,T>
    Map of tracked items to customized objects.
    private int
    Modification count.
  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractTracked constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) void
    Called by the owning Tracker object when it is closed.
    (package private) <M extends Map<? super S, ? super T>>
    M
    copyEntries(M map)
    Copy the tracked items and associated values into the specified map.
    (package private) S[]
    copyKeys(S[] list)
    Copy the tracked items into an array.
    (package private) abstract T
    customizerAdding(S item, R related)
    Call the specific customizer adding method.
    (package private) abstract void
    customizerModified(S item, R related, T object)
    Call the specific customizer modified method.
    (package private) abstract void
    customizerRemoved(S item, R related, T object)
    Call the specific customizer removed method.
    (package private) T
    Return the customized object for the specified item
    (package private) int
    Returns the tracking count for this ServiceTracker object.
    (package private) boolean
    Returns if the tracker is empty.
    (package private) void
    Increment the modification count.
    (package private) void
    setInitial(S[] list)
    Set initial list of items into tracker before events begin to be received.
    (package private) int
    Returns the number of tracked items.
    (package private) void
    track(S item, R related)
    Begin to track an item.
    private void
    trackAdding(S item, R related)
    Common logic to add an item to the tracker used by track and trackInitial.
    (package private) void
    Track the initial list of items.
    (package private) void
    untrack(S item, R related)
    Discontinue tracking the item.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEBUG

      static final boolean DEBUG
      See Also:
    • tracked

      private final Map<S,T> tracked
      Map of tracked items to customized objects.
    • trackingCount

      private int trackingCount
      Modification count. This field is initialized to zero and incremented by modified.
    • adding

      private final List<S> adding
      List of items in the process of being added. This is used to deal with nesting of events. Since events may be synchronously delivered, events can be nested. For example, when processing the adding of a service and the customizer causes the service to be unregistered, notification to the nested call to untrack that the service was unregistered can be made to the track method. Since the ArrayList implementation is not synchronized, all access to this list must be protected by the same synchronized object for thread-safety.
    • closed

      volatile boolean closed
      true if the tracked object is closed. This field is volatile because it is set by one thread and read by another.
    • initial

      private final LinkedList<S> initial
      Initial list of items for the tracker. This is used to correctly process the initial items which could be modified before they are tracked. This is necessary since the initial set of tracked items are not "announced" by events and therefore the event which makes the item untracked could be delivered before we track the item. An item must not be in both the initial and adding lists at the same time. An item must be moved from the initial list to the adding list "atomically" before we begin tracking it. Since the LinkedList implementation is not synchronized, all access to this list must be protected by the same synchronized object for thread-safety.
  • Constructor Details

    • AbstractTracked

      AbstractTracked()
      AbstractTracked constructor.
  • Method Details

    • setInitial

      void setInitial(S[] list)
      Set initial list of items into tracker before events begin to be received. This method must be called from Tracker's open method while synchronized on this object in the same synchronized block as the add listener call.
      Parameters:
      list - The initial list of items to be tracked. null entries in the list are ignored.
    • trackInitial

      void trackInitial()
      Track the initial list of items. This is called after events can begin to be received. This method must be called from Tracker's open method while not synchronized on this object after the add listener call.
    • close

      void close()
      Called by the owning Tracker object when it is closed.
    • track

      void track(S item, R related)
      Begin to track an item.
      Parameters:
      item - Item to be tracked.
      related - Action related object.
    • trackAdding

      private void trackAdding(S item, R related)
      Common logic to add an item to the tracker used by track and trackInitial. The specified item must have been placed in the adding list before calling this method.
      Parameters:
      item - Item to be tracked.
      related - Action related object.
    • untrack

      void untrack(S item, R related)
      Discontinue tracking the item.
      Parameters:
      item - Item to be untracked.
      related - Action related object.
    • size

      int size()
      Returns the number of tracked items.
      Returns:
      The number of tracked items.
    • isEmpty

      boolean isEmpty()
      Returns if the tracker is empty.
      Returns:
      Whether the tracker is empty.
      Since:
      1.5
    • getCustomizedObject

      T getCustomizedObject(S item)
      Return the customized object for the specified item
      Parameters:
      item - The item to lookup in the map
      Returns:
      The customized object for the specified item.
    • copyKeys

      S[] copyKeys(S[] list)
      Copy the tracked items into an array.
      Parameters:
      list - An array to contain the tracked items.
      Returns:
      The specified list if it is large enough to hold the tracked items or a new array large enough to hold the tracked items.
    • modified

      void modified()
      Increment the modification count. If this method is overridden, the overriding method MUST call this method to increment the tracking count.
    • getTrackingCount

      int getTrackingCount()
      Returns the tracking count for this ServiceTracker object. The tracking count is initialized to 0 when this object is opened. Every time an item is added, modified or removed from this object the tracking count is incremented.
      Returns:
      The tracking count for this object.
    • copyEntries

      <M extends Map<? super S, ? super T>> M copyEntries(M map)
      Copy the tracked items and associated values into the specified map.
      Type Parameters:
      M - Type of Map to hold the tracked items and associated values.
      Parameters:
      map - The map into which to copy the tracked items and associated values. This map must not be a user provided map so that user code is not executed while synchronized on this.
      Returns:
      The specified map.
      Since:
      1.5
    • customizerAdding

      abstract T customizerAdding(S item, R related)
      Call the specific customizer adding method. This method must not be called while synchronized on this object.
      Parameters:
      item - Item to be tracked.
      related - Action related object.
      Returns:
      Customized object for the tracked item or null if the item is not to be tracked.
    • customizerModified

      abstract void customizerModified(S item, R related, T object)
      Call the specific customizer modified method. This method must not be called while synchronized on this object.
      Parameters:
      item - Tracked item.
      related - Action related object.
      object - Customized object for the tracked item.
    • customizerRemoved

      abstract void customizerRemoved(S item, R related, T object)
      Call the specific customizer removed method. This method must not be called while synchronized on this object.
      Parameters:
      item - Tracked item.
      related - Action related object.
      object - Customized object for the tracked item.