Package com.pnfsoftware.jeb.util.collect

Class ReferenceCounter<K>

java.lang.Object
com.pnfsoftware.jeb.util.collect.ReferenceCounter<K>
Type Parameters:
K - counted object type
@Ser public class ReferenceCounter<K> extends Object
A simple, thread-safe object reference counter. A counter can be associated to any object of the provided K type.

Note that this utility class has nothing to do with Garbage Collection reference counting.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ReferenceCounter()
    Create a new reference counter.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Reset the reference counter.
    Map<K,Integer>
    copyToMap()
    Copy the counters to a map.
    int
    dec(K key)
    Unrecord an object, ie decrement its reference counter by one.
    String
    formatAllReferences()
    Format all references in descending order.
    String
    formatTopReferences(int top)
    Format the top references (= descending order) counted referenced by the counter.
    int
    get(K key)
    Get the reference counter for an object.
    Map<K,Integer>
    getAsMap()
    Get a read-only map of (referenced object -> count).
    int
    getCount()
    Get the total count for all the references actively counted by this counter.
    boolean
    has(K key)
    Check if an object is currently referenced, ie its reference counter is greater or equal than zero.
    int
    inc(K key)
    Record an object, ie increment its reference counter.
    boolean
    isEmpty()
    Determine whether there are references actively tracked by this counter.
    Set<K>
    keys()
    Retrieve the tracked keys.
    void
    load(Collection<? extends K> coll)
    Load a collection of objects by incrementing the counter for each object.
    Collection<K>
    orderedKeys(boolean descending)
    Retrieve keys ordered by their counters.
    boolean
    remove(K key)
    Remove an object from tracking.
    int
    size()
    Get the number of references actively counted by this counter.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ReferenceCounter

      public ReferenceCounter()
      Create a new reference counter.

  • Method Details

    • clear

      public void clear()
      Reset the reference counter.

    • isEmpty

      public boolean isEmpty()
      Determine whether there are references actively tracked by this counter.
      Returns:
      true if no object is tracked

    • size

      public int size()
      Get the number of references actively counted by this counter.
      Returns:
      number of distinct tracked objects

    • getCount

      public int getCount()
      Get the total count for all the references actively counted by this counter.
      Returns:
      sum of all counters

    • inc

      public int inc(K key)
      Record an object, ie increment its reference counter. Will raise an IllegalStateException if the counter exceeds the capacity of a signed integer.
      Parameters:
      key - object
      Returns:
      the updated counter for this object

    • dec

      public int dec(K key)
      Unrecord an object, ie decrement its reference counter by one. If the object is currently untracked, an exception will be raised.
      Parameters:
      key - object
      Returns:
      the updated counter for this object
      Throws:
      IllegalArgumentException - if the object is not present

    • has

      public boolean has(K key)
      Check if an object is currently referenced, ie its reference counter is greater or equal than zero.
      Parameters:
      key - object
      Returns:
      true if the object is referenced

    • get

      public int get(K key)
      Get the reference counter for an object.
      Parameters:
      key - object
      Returns:
      the counter; 0 if the object is currently not tracked

    • getAsMap

      public Map<K,Integer> getAsMap()
      Get a read-only map of (referenced object -> count). To be used in a "this counter"-synchronized block.
      Returns:
      read-only view of the internal map

    • remove

      public boolean remove(K key)
      Remove an object from tracking. This method is equivalent to decrementing the object counter until zero.
      Parameters:
      key - object
      Returns:
      true if the object was actually referenced (ie its counter was >= 1), false if it was not

    • load

      public void load(Collection<? extends K> coll)
      Load a collection of objects by incrementing the counter for each object.
      Parameters:
      coll - objects to count

    • keys

      public Set<K> keys()
      Retrieve the tracked keys.
      Returns:
      copy of the key set

    • orderedKeys

      public Collection<K> orderedKeys(boolean descending)
      Retrieve keys ordered by their counters.
      Parameters:
      descending - true to sort by descending counter values
      Returns:
      ordered collection of keys

    • copyToMap

      public Map<K,Integer> copyToMap()
      Copy the counters to a map.
      Returns:
      copy of the counter map

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • formatAllReferences

      public String formatAllReferences()
      Format all references in descending order.
      Returns:
      a string

    • formatTopReferences

      public String formatTopReferences(int top)
      Format the top references (= descending order) counted referenced by the counter.
      Parameters:
      top - the number of top references to format; a negative number means to format all references
      Returns:
      a string