Package: org.codehaus.groovy.runtime.memoize

## [Java] Class StampedCommonCache<K, V>

- org.codehaus.groovy.runtime.memoize.StampedCommonCache

- All Implemented Interfaces and Traits:
    FlexibleCache, ValueConvertable, Serializable

      @ThreadSafe
      public class StampedCommonCache<K, V>
      extends Object
      implements FlexibleCache, ValueConvertable, 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)

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

- - ### Constructor Summary

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

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `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.
    `` | `public Map<K, V>` | `clearAll()` * Clear the cache * Returns: returns the content of the cleared map
    `` | `public boolean` | `containsKey(Object key)` * Determines if the cache contains an entry for the specified key. * Parameters: `key` - key whose presence in this cache is to be tested. * Returns: true if the cache contains a mapping for the specified key
    `` | `public boolean` | `containsValue(Object value)` Determines whether the cache contains the specified stored value.
    `` | `public Object` | `convertValue(V value)` Returns the stored value unchanged.
    `` | `public Set<Entry<K, V>>` | `entrySet()` Returns a live view of the cache entries.
    `` | `public V` | `get(Object key)` * Gets a value from the cache * Parameters: `key` - the key whose associated value is to be returned * Returns: the value, or null, if it does not exist.
    `` | `public V` | `getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider)` * Try to get the value from cache. * If not found, create the value by ValueProvider and put it into the cache, at last return the value. * * Parameters: `key` - the key to look up * `valueProvider` - provide the value if the associated value not found * Returns: the cached value
    `` | `public V` | `getAndPut(K key, 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. * * 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
    `` | `public boolean` | `isEmpty()` Returns whether the cache currently holds no entries.
    `` | `public Set<K>` | `keySet()` Returns a live view of the keys in this cache.
    `` | `public Set<K>` | `keys()` * Get all keys associated to cached values * Returns: all keys
    `` | `public V` | `put(K key, V value)` * Associates the specified value with the specified key in the cache. * 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.
    `` | `public void` | `putAll(Map<? extends K, ? extends V> m)` Copies all mappings from the supplied map into this cache.
    `` | `public V` | `remove(Object key)` * Remove the cached value by the key * Parameters: `key` - of the cached value * Returns: returns the removed value
    `` | `public int` | `size()` * Get the size of the cache * Returns: the size of the cache
    `` | `public Collection<V>` | `values()` * Get all cached values * Returns: all cached values

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public StampedCommonCache()

      Constructs a cache with unlimited size

    - #### public StampedCommonCache(int initialCapacity, int maxSize, 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

    - #### 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

    - #### 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)

    - #### public StampedCommonCache(Map<K, V> map)

      Constructs a cache backed by the specified Map instance

      Parameters:
        `map` - the Map instance

  - ### Method Detail

    - #### 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.

    - #### public Map<K, V> clearAll()

      * Clear the cache *

      Returns:
        returns the content of the cleared map

    - #### public boolean containsKey(Object key)

      * Determines if the cache contains an entry for the specified key. *

      Parameters:
        `key` - key whose presence in this cache is to be tested. *
      Returns:
        true if the cache contains a mapping for the specified key

    - #### public boolean containsValue(Object value)

      Determines whether the cache contains the specified stored value.

      Parameters:
        `value` - the value whose presence should be tested
      Returns:
        `true` if the cache contains the value

    - #### public Object convertValue(V value)

      Returns the stored value unchanged.

      Parameters:
        `value` - the stored value
      Returns:
        `value`

    - #### public Set<Entry<K, V>> entrySet()

      Returns a live view of the cache entries.

      Returns:
        the cache entries

    - #### public V get(Object key)

      * Gets a value from the cache *

      Parameters:
        `key` - the key whose associated value is to be returned *
      Returns:
        the value, or null, if it does not exist.

    - #### public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider)

      * Try to get the value from cache. * If not found, create the value by ValueProvider and put it into the cache, at last return the value. * *

      Parameters:
        `key` - the key to look up *
        `valueProvider` - provide the value if the associated value not found *
      Returns:
        the cached value

    - #### public V getAndPut(K key, 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. * *

      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

    - #### public boolean isEmpty()

      Returns whether the cache currently holds no entries.

      Returns:
        `true` if the cache is empty

    - #### public Set<K> keySet()

      Returns a live view of the keys in this cache.

      Returns:
        the cache keys

    - #### public Set<K> keys()

      * Get all keys associated to cached values *

      Returns:
        all keys

    - #### public V put(K key, V value)

      * Associates the specified value with the specified key in the cache. *

      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.

    - #### public void putAll(Map<? extends K, ? extends V> m)

      Copies all mappings from the supplied map into this cache.

      Parameters:
        `m` - the mappings to copy

    - #### public V remove(Object key)

      * Remove the cached value by the key *

      Parameters:
        `key` - of the cached value *
      Returns:
        returns the removed value

    - #### public int size()

      * Get the size of the cache *

      Returns:
        the size of the cache

    - #### public Collection<V> values()

      * Get all cached values *

      Returns:
        all cached values