Package com.cedarsoftware.util

Class TrackingMap<K,V>

java.lang.Object
com.cedarsoftware.util.TrackingMap<K,V>
Type Parameters:
K - the type of keys maintained by this map
V - the type of mapped values
All Implemented Interfaces:
Map<K,V>
public class TrackingMap<K,V> extends Object implements Map<K,V>
A wrapper around a Map that tracks which keys have been accessed via get or containsKey methods. This is useful for scenarios where it's necessary to monitor usage patterns of keys in a map, such as identifying unused entries or optimizing memory usage by expunging rarely accessed keys.

Usage Example: 


 Map<String, Integer> originalMap = new HashMap<>();
 originalMap.put("apple", 1);
 originalMap.put("banana", 2);
 originalMap.put("cherry", 3);

 TrackingMap<String, Integer> trackingMap = new TrackingMap<>(originalMap);

 // Access some keys
 trackingMap.get("apple");
 trackingMap.containsKey("banana");

 // Expunge unused keys
 trackingMap.expungeUnused();

 // Now, "cherry" has been removed as it was not accessed
 System.out.println(trackingMap.keySet()); // Outputs: [apple, banana]

Thread Safety: This class is not thread-safe. If multiple threads access a TrackingMap concurrently and at least one of the threads modifies the map structurally, it must be synchronized externally.

Note: The expungeUnused() method removes all entries that have not been accessed via get(Object) or containsKey(Object) since the map was created or since the last call to expungeUnused().

Author:
Sean Kellner
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

  • Constructor Details

    • TrackingMap

      public TrackingMap(Map<K,V> map)
      Wraps the provided Map with a TrackingMap.
      Parameters:
      map - the Map to be wrapped and tracked
      Throws:
      IllegalArgumentException - if the provided map is null

  • Method Details

    • get

      public V get(Object key)
      Retrieves the value associated with the specified key and marks the key as accessed.
      Specified by:
      get in interface Map<K,V>
      Parameters:
      key - the key whose associated value is to be returned
      Returns:
      the value associated with the specified key, or null if no mapping exists

    • put

      public V put(K key, V value)
      Associates the specified value with the specified key in this map.
      Specified by:
      put in interface Map<K,V>
      Parameters:
      key - key with which the specified value is to be associated
      value - value to be associated with the specified key
      Returns:
      the previous value associated with key, or null if there was no mapping

    • containsKey

      public boolean containsKey(Object key)
      Returns true if this map contains a mapping for the specified key. Marks the key as accessed.
      Specified by:
      containsKey in interface Map<K,V>
      Parameters:
      key - key whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified key

    • putAll

      public void putAll(Map<? extends K,? extends V> m)
      Copies all the mappings from the specified map to this map.
      Specified by:
      putAll in interface Map<K,V>
      Parameters:
      m - mappings to be stored in this map
      Throws:
      NullPointerException - if the specified map is null

    • remove

      public V remove(Object key)
      Removes the mapping for a key from this map if it is present. Also removes the key from the set of accessed keys.
      Specified by:
      remove in interface Map<K,V>
      Parameters:
      key - key whose mapping is to be removed from the map
      Returns:
      the previous value associated with key, or null if there was no mapping

    • size

      public int size()
      Specified by:
      size in interface Map<K,V>
      Returns:
      the number of key-value mappings in this map

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Map<K,V>
      Returns:
      true if this map contains no key-value mappings

    • equals

      public boolean equals(Object other)
      Compares the specified object with this map for equality.
      Specified by:
      equals in interface Map<K,V>
      Overrides:
      equals in class Object
      Parameters:
      other - object to be compared for equality with this map
      Returns:
      true if the specified object is equal to this map

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Map<K,V>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this map

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      a string representation of this map

    • clear

      public void clear()
      Removes all the mappings from this map. The map will be empty after this call returns. Also clears the set of accessed keys.
      Specified by:
      clear in interface Map<K,V>

    • containsValue

      public boolean containsValue(Object value)
      Returns true if this map maps one or more keys to the specified value.
      Specified by:
      containsValue in interface Map<K,V>
      Parameters:
      value - value whose presence in this map is to be tested
      Returns:
      true if this map maps one or more keys to the specified value

    • values

      public Collection<V> values()
      Specified by:
      values in interface Map<K,V>
      Returns:
      a Collection view of the values contained in this map

    • keySet

      public Set<K> keySet()
      Specified by:
      keySet in interface Map<K,V>
      Returns:
      a Set view of the keys contained in this map

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Specified by:
      entrySet in interface Map<K,V>
      Returns:
      a Set view of the mappings contained in this map

    • expungeUnused

      public void expungeUnused()
      Remove the entries from the Map that have not been accessed by .get() or .containsKey().

    • informAdditionalUsage

      public void informAdditionalUsage(Collection<K> additional)
      Adds the accessed keys from another TrackingMap to this map's set of accessed keys. This can be useful when merging usage information from multiple tracking maps.
      Parameters:
      additional - another TrackingMap whose accessed keys are to be added

    • informAdditionalUsage

      public void informAdditionalUsage(TrackingMap<K,V> additional)
      Add the used keys from the passed in TrackingMap to this TrackingMap's keysUsed. This can cause the readKeys to include entries that are not in wrapped Maps keys.
      Parameters:
      additional - TrackingMap whose used keys are to be added to this map's used keys.

    • keysUsed

      public Set<K> keysUsed()
      Returns a Set of keys that have been accessed via get or containsKey.
      Returns:
      a Set of accessed keys

    • getWrappedMap

      public Map<K,V> getWrappedMap()
      Returns the underlying Map that this TrackingMap wraps.
      Returns:
      the wrapped Map