Package org.codehaus.groovy.runtime.memoize

# Class StampedCommonCache<K,V>

java.lang.Object
org.codehaus.groovy.runtime.memoize.StampedCommonCache<K,V>

Type Parameters:
  `K` - type of the keys
  `V` - type of the values

All Implemented Interfaces:
  `Serializable`, `Map<K,V>`, `EvictableCache<K,V>`, `FlexibleCache<K,V>`, `MemoizeCache<K,V>`, `ValueConvertable<V,Object>`

@ThreadSafe public class StampedCommonCache<K,V> extends Object implements FlexibleCache<K,V>, ValueConvertable<V,Object>, Serializable
Represents a simple key-value cache, which is thread safe and backed by a `Map` instance. StampedCommonCache has better performance than `ConcurrentCommonCache`, but it is not reentrant, in other words, it may cause deadlock if `getAndPut(Object, MemoizeCache.ValueProvider)` or `getAndPut(Object, MemoizeCache.ValueProvider, boolean)` is called recursively: readlock -> upgrade to writelock -> readlock (fails to get and waits forever)

Since:
  3.0.0
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface org.codehaus.groovy.runtime.memoize.EvictableCache

  `EvictableCache.Action<K,V,R>, EvictableCache.EvictionStrategy`

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K extends Object,V extends Object>`

  ## Nested classes/interfaces inherited from interface org.codehaus.groovy.runtime.memoize.MemoizeCache

  `MemoizeCache.ValueProvider<K,V>`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StampedCommonCache()`
  Constructs a cache with unlimited size
  `StampedCommonCache(int maxSize)`
  Constructs an LRU cache with the default initial capacity(16)
  `StampedCommonCache(int initialCapacity, int maxSize)`
  Constructs an LRU cache with the specified initial capacity and max size.
  `StampedCommonCache(int initialCapacity, int maxSize, EvictableCache.EvictionStrategy evictionStrategy)`
  Constructs a cache with limited size
  `StampedCommonCache(Map<K,V> map)`
  Constructs a cache backed by the specified `Map` instance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cleanUpNullReferences()`
  Invoked when some of the held SoftReferences have been evicted by the garbage collector and so should be removed from the cache.
  `Map<K,V>`
  `clearAll()`
  Clear the cache
  `boolean`
  `containsKey(Object key)`
  Determines if the cache contains an entry for the specified key.
  `boolean`
  `containsValue(Object value)`
  Determines whether the cache contains the specified stored value.
  `Object`
  `convertValue(V value)`
  Returns the stored value unchanged.
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  Returns a live view of the cache entries.
  `V`
  `get(Object key)`
  Gets a value from the cache
  `V`
  `getAndPut(K key, MemoizeCache.ValueProvider<? super K,? extends V> valueProvider)`
  Try to get the value from cache.
  `V`
  `getAndPut(K key, MemoizeCache.ValueProvider<? super K,? extends V> valueProvider, boolean shouldCache)`
  Returns the value associated with `key`, creating it with the supplied provider when necessary and optionally caching the result.
  `boolean`
  `isEmpty()`
  Returns whether the cache currently holds no entries.
  `Set<K>`
  `keys()`
  Get all keys associated to cached values
  `Set<K>`
  `keySet()`
  Returns a live view of the keys in this cache.
  `V`
  `put(K key, V value)`
  Associates the specified value with the specified key in the cache.
  `void`
  `putAll(Map<? extends K,? extends V> m)`
  Copies all mappings from the supplied map into this cache.
  `V`
  `remove(Object key)`
  Remove the cached value by the key
  `int`
  `size()`
  Get the size of the cache
  `Collection<V>`
  `values()`
  Get all cached values

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

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

  ### Methods inherited from interface org.codehaus.groovy.runtime.memoize.EvictableCache

  `clear`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Constructor Details

  - ### StampedCommonCache

    public StampedCommonCache()
    Constructs a cache with unlimited size

  - ### StampedCommonCache

    public StampedCommonCache(int initialCapacity, int maxSize, EvictableCache.EvictionStrategy evictionStrategy)
    Constructs a cache with limited size
    Parameters:
      `initialCapacity` - initial capacity of the cache
      `maxSize` - max size of the cache
      `evictionStrategy` - LRU or FIFO, see `EvictableCache.EvictionStrategy`

  - ### StampedCommonCache

    public StampedCommonCache(int initialCapacity, int maxSize)
    Constructs an LRU cache with the specified initial capacity and max size. The LRU cache is slower than `LRUCache`
    Parameters:
      `initialCapacity` - initial capacity of the LRU cache
      `maxSize` - max size of the LRU cache

  - ### StampedCommonCache

    public StampedCommonCache(int maxSize)
    Constructs an LRU cache with the default initial capacity(16)
    Parameters:
      `maxSize` - max size of the LRU cache
    See Also:
      - `StampedCommonCache(int, int)`

  - ### StampedCommonCache

    public StampedCommonCache(Map<K,V> map)
    Constructs a cache backed by the specified `Map` instance
    Parameters:
      `map` - the `Map` instance

- ## Method Details

  - ### get

    public V get(Object key)
    Gets a value from the cache
    Specified by:
      `get` in interface `Map<K,V>`
    Specified by:
      `get` in interface `MemoizeCache<K,V>`
    Parameters:
      `key` - the key whose associated value is to be returned
    Returns:
      the value, or null, if it does not exist.

  - ### put

    public V put(K key, V value)
    Associates the specified value with the specified key in the cache.
    Specified by:
      `put` in interface `Map<K,V>`
    Specified by:
      `put` in interface `MemoizeCache<K,V>`
    Parameters:
      `key` - key with which the specified value is to be associated
      `value` - value to be associated with the specified key
    Returns:
      null, or the old value if the key associated with the specified key.

  - ### getAndPut

    public V getAndPut(K key, MemoizeCache.ValueProvider<? super K,? extends V> valueProvider)
    Try to get the value from cache. If not found, create the value by `MemoizeCache.ValueProvider` and put it into the cache, at last return the value.
    Specified by:
      `getAndPut` in interface `MemoizeCache<K,V>`
    Parameters:
      `key` - the key to look up
      `valueProvider` - provide the value if the associated value not found
    Returns:
      the cached value

  - ### getAndPut

    public V getAndPut(K key, MemoizeCache.ValueProvider<? super K,? extends V> valueProvider, boolean shouldCache)
    Returns the value associated with `key`, creating it with the supplied provider when necessary and optionally caching the result.
    Specified by:
      `getAndPut` in interface `FlexibleCache<K,V>`
    Parameters:
      `key` - the key to look up
      `valueProvider` - supplies a value when the key is not cached
      `shouldCache` - whether a newly created value should be stored
    Returns:
      the cached or newly created value

  - ### values

    public Collection<V> values()
    Get all cached values
    Specified by:
      `values` in interface `EvictableCache<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Returns:
      all cached values

  - ### entrySet

    public Set<Map.Entry<K,V>> entrySet()
    Returns a live view of the cache entries.
    Specified by:
      `entrySet` in interface `Map<K,V>`
    Returns:
      the cache entries

  - ### keys

    public Set<K> keys()
    Get all keys associated to cached values
    Specified by:
      `keys` in interface `EvictableCache<K,V>`
    Returns:
      all keys

  - ### containsKey

    public boolean containsKey(Object key)
    Determines if the cache contains an entry for the specified key.
    Specified by:
      `containsKey` in interface `EvictableCache<K,V>`
    Specified by:
      `containsKey` in interface `Map<K,V>`
    Parameters:
      `key` - key whose presence in this cache is to be tested.
    Returns:
      true if the cache contains a mapping for the specified key

  - ### containsValue

    public boolean containsValue(Object value)
    Determines whether the cache contains the specified stored value.
    Specified by:
      `containsValue` in interface `Map<K,V>`
    Parameters:
      `value` - the value whose presence should be tested
    Returns:
      `true` if the cache contains the value

  - ### size

    public int size()
    Get the size of the cache
    Specified by:
      `size` in interface `EvictableCache<K,V>`
    Specified by:
      `size` in interface `Map<K,V>`
    Returns:
      the size of the cache

  - ### isEmpty

    public boolean isEmpty()
    Returns whether the cache currently holds no entries.
    Specified by:
      `isEmpty` in interface `Map<K,V>`
    Returns:
      `true` if the cache is empty

  - ### remove

    public V remove(Object key)
    Remove the cached value by the key
    Specified by:
      `remove` in interface `EvictableCache<K,V>`
    Specified by:
      `remove` in interface `Map<K,V>`
    Parameters:
      `key` - of the cached value
    Returns:
      returns the removed value

  - ### putAll

    public void putAll(Map<? extends K,? extends V> m)
    Copies all mappings from the supplied map into this cache.
    Specified by:
      `putAll` in interface `Map<K,V>`
    Parameters:
      `m` - the mappings to copy

  - ### keySet

    public Set<K> keySet()
    Returns a live view of the keys in this cache.
    Specified by:
      `keySet` in interface `Map<K,V>`
    Returns:
      the cache keys

  - ### clearAll

    public Map<K,V> clearAll()
    Clear the cache
    Specified by:
      `clearAll` in interface `EvictableCache<K,V>`
    Returns:
      returns the content of the cleared map

  - ### cleanUpNullReferences

    public void cleanUpNullReferences()
    Invoked when some of the held SoftReferences have been evicted by the garbage collector and so should be removed from the cache. The implementation must ensure that concurrent invocations of all methods on the cache may occur from other threads and thus should protect any shared resources.
    Specified by:
      `cleanUpNullReferences` in interface `MemoizeCache<K,V>`

  - ### convertValue

    public Object convertValue(V value)
    Returns the stored value unchanged.
    Specified by:
      `convertValue` in interface `ValueConvertable<K,V>`
    Parameters:
      `value` - the stored value
    Returns:
      `value`