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>`, `FlexibleEvictableCache<K,V>`, `MemoizeCache<K,V>`, `ValueConvertable<V,Object>`

@ThreadSafe public class StampedCommonCache<K,V> extends Object implements FlexibleEvictableCache<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)`
  `Object`
  `convertValue(V value)`
  convert the original value to the target value
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  `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)`
  `boolean`
  `isEmpty()`
  `Set<K>`
  `keys()`
  Get all keys associated to cached values
  `Set<K>`
  `keySet()`
  `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)`
  `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)
    Specified by:
      `getAndPut` in interface `FlexibleEvictableCache<K,V>`

  - ### 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()
    Specified by:
      `entrySet` in interface `Map<K,V>`

  - ### 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)
    Specified by:
      `containsValue` in interface `Map<K,V>`

  - ### 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()
    Specified by:
      `isEmpty` in interface `Map<K,V>`

  - ### 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)
    Specified by:
      `putAll` in interface `Map<K,V>`

  - ### keySet

    public Set<K> keySet()
    Specified by:
      `keySet` in interface `Map<K,V>`

  - ### 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)
    convert the original value to the target value
    Specified by:
      `convertValue` in interface `ValueConvertable<K,V>`
    Parameters:
      `value` - the original value
    Returns:
      the converted value