de.caff.generics

## Class LeastRecentlyUsedCache<K,V>

- java.lang.Object
- - de.caff.generics.LeastRecentlyUsedCache<K,V>

- Type Parameters:
    `K` - key type of map, as always keys are expected to not mutate during the lifetime of this object
    `V` - value type of map
  Direct Known Subclasses:
    RecreatingLeastRecentlyUsedCache

      public class LeastRecentlyUsedCache<K,V>
      extends java.lang.Object

  A map which implements a least recently used cache.

  Usage here means that the latest value which is either add by `put(Object, Object)` or retrieved by `get(Object)` is the least recently used one.

  The implemented map basically keeps only soft references to its values, but not its keys. Therefore keys and values must be of different types, otherwise store values will not be freed, ever.

  This does deliberately not implement `Map` as that has too many methods mot making much sense here.

  Attention: `null` values are not allowed for this map, as `null` is used to mark valeus which are removed by the garbage collector

  See `RecreatingLeastRecentlyUsedCache` for a way to include an automatic recreation of garbage-collected values.

  Since:
    May 10, 2021
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.util.Map<K,java.lang.ref.SoftReference<V>>` | `map`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LeastRecentlyUsedCache(int leastRecentLimit)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cleanup()` Remove all key-value pairs which are no longer available.
    `void` | `clear()` Remove all entries from this cache.
    `V` | `computeIfAbsent(K key, java.util.function.Function<? super K,? extends V> creator)` Get the value for the given key, or compute a new value and add it for the given key.
    `V` | `get(K key)` Get the value for the given key.
    `int` | `getLeastRecentCacheDepth()` Get the maximum number of values kept in the LRU cache.
    `java.util.List<V>` | `getLeastRecentlyUsed()` Get the values in the LRU cache in order.
    `int` | `getNumGarbageCollected()` Get the number of times an entry was garbage collected.
    `int` | `getNumHits()` Get the number of times a cached value was successfully retrieved.
    `int` | `getNumMisses()` Get the number of times an entry was not found in the cache.
    `boolean` | `isEmpty()` Is this mapping empty?
    `java.util.Set<K>` | `keys()` Get the keys currently valid in this cache.
    `void` | `put(K key, V value)` Put a new key-value pair into this cache.
    `V` | `remove(K key)` Remove a key-value pair from this cache.
    `int` | `size()` Get the size of this mapping.

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

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

- - ### Field Detail

    - #### map

          @NotNull
          protected final java.util.Map<K,java.lang.ref.SoftReference<V>> map

  - ### Constructor Detail

    - #### LeastRecentlyUsedCache

          public LeastRecentlyUsedCache(int leastRecentLimit)

      Constructor. This just keeps up to `leastRecentLimit` values cached. It does not define a recreator, therefore values removed by garbage collection are gone, and have to be recreated and readded to this maps elsewhere.
      Parameters:
        `leastRecentLimit` - maximal number of cached values, non-negative

  - ### Method Detail

    - #### cleanup

          public void cleanup()

      Remove all key-value pairs which are no longer available.

    - #### size

          public int size()

      Get the size of this mapping. This implicitly calls `cleanup()` before returning the size, but as garbage collection can happen any time users should not depend too much on the returned value.
      Returns:
        number of currently cached values

    - #### getLeastRecentCacheDepth

          public int getLeastRecentCacheDepth()

      Get the maximum number of values kept in the LRU cache. This cache may keep a greater number of values as long as there is enough memory.
      Returns:
        cache limit

    - #### isEmpty

          public boolean isEmpty()

      Is this mapping empty? This implicitly calls `cleanup()` before returning the answer but as garbage collection can happen any time users should not depend too much on the returned value.
      Returns:
        number of currently cached values

    - #### get

          @Nullable
          public V get(@NotNull
                                 K key)

      Get the value for the given key.
      Parameters:
        `key` - key associated with the requested value
      Returns:
        `null` when the required value was never added to this cache or when it was garbage collected in the meantime, otherwise the cached object associated with the given key

    - #### put

          public void put(K key,
                          @NotNull
                          V value)

      Put a new key-value pair into this cache.
      Parameters:
        `key` - key for retrieving the cached value
        `value` - value to cache

    - #### computeIfAbsent

          public V computeIfAbsent(K key,
                                   @NotNull
                                   java.util.function.Function<? super K,? extends V> creator)

      Get the value for the given key, or compute a new value and add it for the given key.
      Parameters:
        `key` - key of requested value
        `creator` - creator for new value if key is (no longer) present
      Returns:
        stored or newly created vale, `null` only if creator returns `null`

    - #### keys

          @NotNull
          public java.util.Set<K> keys()

      Get the keys currently valid in this cache. This calls `cleanup()` before the keys are returned. This is just a snapshot, don't depend too much on the returned keys.
      Returns:
        set of currently valid keys

    - #### remove

          @Nullable
          public V remove(K key)

      Remove a key-value pair from this cache.
      Parameters:
        `key` - key of the key-value pair
      Returns:
        removed object if it was still cached, or `null` if the object was either never cached at all or has been garbage collected

    - #### clear

          public void clear()

      Remove all entries from this cache.

    - #### getLeastRecentlyUsed

          @NotNull
          public java.util.List<V> getLeastRecentlyUsed()

      Get the values in the LRU cache in order.
      Returns:
        values in the LRU cache, most least recently used item first

    - #### getNumHits

          public int getNumHits()

      Get the number of times a cached value was successfully retrieved.
      Returns:
        number of cache hits

    - #### getNumGarbageCollected

          public int getNumGarbageCollected()

      Get the number of times an entry was garbage collected.
      Returns:
        number of garbage collected entries

    - #### getNumMisses

          public int getNumMisses()

      Get the number of times an entry was not found in the cache.
      Returns:
        number of cache misses