Class 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 java.lang.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 java.util.List<S> adding
      List of items in the process of being added.
      (package private) boolean closed
      true if the tracked object is closed.
      (package private) static boolean DEBUG  
      private java.util.LinkedList<S> initial
      Initial list of items for the tracker.
      private java.util.Map<S,​T> tracked
      Map of tracked items to customized objects.
      private int trackingCount
      Modification count.
    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractTracked()
      AbstractTracked constructor.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) void close()
      Called by the owning Tracker object when it is closed.
      (package private) <M extends java.util.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 getCustomizedObject​(S item)
      Return the customized object for the specified item
      (package private) int getTrackingCount()
      Returns the tracking count for this ServiceTracker object.
      (package private) boolean isEmpty()
      Returns if the tracker is empty.
      (package private) void modified()
      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 size()
      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 trackInitial()
      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 Detail

      • tracked

        private final java.util.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 java.util.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 java.util.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 Detail

      • AbstractTracked

        AbstractTracked()
        AbstractTracked constructor.
    • Method Detail

      • 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 java.util.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.