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)`
    `` | `public Object` | `convertValue(V value)` {@inheritDoc}
    `` | `public Set<Entry<K, V>>` | `entrySet()`
    `` | `public V` | `get(Object key)` {@inheritDoc}
    `` | `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)`
    `` | `public boolean` | `isEmpty()`
    `` | `public Set<K>` | `keySet()`
    `` | `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)`
    `` | `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)

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

      {@inheritDoc}

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

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

      {@inheritDoc}

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

    - #### public boolean isEmpty()

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

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

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