Package ghidra.util.timer

# Class GTimerCache<K,V>

java.lang.Object
ghidra.util.timer.GTimerCache<K,V>

Type Parameters:
  `K` - the key
  `V` - the value

public class GTimerCache<K,V> extends Object
Class for caching key,value entries for a limited time and cache size. Entries in this cache will be removed after the cache duration time has passed. If the cache ever exceeds its capacity, the least recently used entry will be removed.

This class uses a `LinkedHashMap` with it ordering mode set to "access order". This means that iterating through keys, values, or entries of the map will be presented oldest first. Inserting or accessing an entry in the map will move the entry to the back of the list, thus making it the youngest. This means that entries closest to or past expiration will be presented first.

This class is designed to be subclassed for two specific cases. The first case is for when additional processing is required when an entry is removed from the cache. This typically would be for cases where resources need to be released, such as closing a File or disposing the object. The second reason to subclass this cache is to get more control of expiring values. Overriding `shouldRemoveFromCache(Object, Object)`, which gets called when an entry's time has expired, gives the client a chance to decide if the entry should be removed.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GTimerCache(Duration lifetime, int capacity)`
  Constructs new GTimerCache with a duration for cached entries and a maximum number of entries to cache.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clears all the values in the cache.
  `boolean`
  `containsKey(K key)`
  Returns true if the cache contains a value for the given key.
  `V`
  `get(K key)`
  Returns the value for the given key.
  `V`
  `put(K key, V value)`
  Adds an key,value entry to the cache
  `V`
  `remove(K key)`
  Removes the cache entry with the given key.
  `void`
  `setCapacity(int capacity)`
  Sets the capacity for this cache.
  `void`
  `setDuration(Duration duration)`
  Sets the duration for keeping cached values.
  `protected boolean`
  `shouldRemoveFromCache(K key, V value)`
  Called when an item's cache time has expired to determine if the item should be removed from the cache.
  `int`
  `size()`
  Returns the number of entries in the cache.
  `protected void`
  `valueAdded(K key, V value)`
  Called when an value is being added to the cache.
  `protected void`
  `valueRemoved(K key, V value)`
  Called when an item is being removed from the cache.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### GTimerCache

    public GTimerCache(Duration lifetime, int capacity)
    Constructs new GTimerCache with a duration for cached entries and a maximum number of entries to cache.
    Parameters:
      `lifetime` - the duration that a key,value will remain in the cache without being accessed (accessing a cached entry resets its time)
      `capacity` - the maximum number of entries in the cache before least recently used entries are removed

- ## Method Details

  - ### setCapacity

    public void setCapacity(int capacity)
    Sets the capacity for this cache. If this cache currently has more values than the new capacity, oldest values will be removed.
    Parameters:
      `capacity` - the new capacity for this cache

  - ### setDuration

    public void setDuration(Duration duration)
    Sets the duration for keeping cached values.
    Parameters:
      `duration` - the length of time to keep a cached value

  - ### put

    public V put(K key, V value)
    Adds an key,value entry to the cache
    Parameters:
      `key` - the key with which the value is associated
      `value` - the value being cached
    Returns:
      The previous value associated with the key or null if no previous value

  - ### remove

    public V remove(K key)
    Removes the cache entry with the given key.
    Parameters:
      `key` - the key of the entry to remove
    Returns:
      the value removed or null if the key wasn't in the cache

  - ### containsKey

    public boolean containsKey(K key)
    Returns true if the cache contains a value for the given key.
    Parameters:
      `key` - the key to check if it is in the cache
    Returns:
      true if the cache contains a value for the given key

  - ### size

    public int size()
    Returns the number of entries in the cache.
    Returns:
      the number of entries in the cache

  - ### get

    public V get(K key)
    Returns the value for the given key. Also, resets time the associated with this entry.
    Parameters:
      `key` - the key to retrieve a value
    Returns:
      the value for the given key

  - ### clear

    public void clear()
    Clears all the values in the cache. The expired callback will be called for each entry that was in the cache.

  - ### valueRemoved

    protected void valueRemoved(K key, V value)
    Called when an item is being removed from the cache. This method is for use by subclasses that need to do more processing on items as they are removed, such as releasing resources.

    Note: this method will always be called from within a synchronized block. Subclasses should be careful if they make any external calls from within this method.

    Parameters:
      `key` - The key of the value being removed
      `value` - the value that is being removed

  - ### valueAdded

    protected void valueAdded(K key, V value)
    Called when an value is being added to the cache. This method is for use by subclasses that need to do more processing on items when they are added to the cache.

    Note: this method will always be called from within a synchronized block. Subclasses should be careful if they make any external calls from within this method.

    Parameters:
      `key` - The key of the value being added
      `value` - the new value

  - ### shouldRemoveFromCache

    protected boolean shouldRemoveFromCache(K key, V value)
    Called when an item's cache time has expired to determine if the item should be removed from the cache. The default behavior is to remove an item when its time has expired. Subclasses can override this method to have more control over expiring value removal.

    Note: this method will always be called from within a synchronized block. Subclasses should be careful if they make any external calls from within this method.

    Parameters:
      `key` - the key of the item whose time has expired
      `value` - the value of the item whose time has expired
    Returns:
      true if the item should be removed, false otherwise