org.apache.groovy.util.concurrentlinkedhashmap

## Class ConcurrentLinkedHashMap<K,V>

- java.lang.Object
- - java.util.AbstractMap<K,V>
  - - org.apache.groovy.util.concurrentlinkedhashmap.ConcurrentLinkedHashMap<K,V>

- Type Parameters:
    `K` - the type of keys maintained by this map
    `V` - the type of mapped values
  All Implemented Interfaces:
    java.io.Serializable, java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>

      @ThreadSafe
      public final class ConcurrentLinkedHashMap<K,V>
      extends java.util.AbstractMap<K,V>
      implements java.util.concurrent.ConcurrentMap<K,V>, java.io.Serializable

  A hash table supporting full concurrency of retrievals, adjustable expected concurrency for updates, and a maximum capacity to bound the map by. This implementation differs from `ConcurrentHashMap` in that it maintains a page replacement algorithm that is used to evict an entry when the map has exceeded its capacity. Unlike the `Java Collections Framework`, this map does not have a publicly visible constructor and instances are created through a `ConcurrentLinkedHashMap.Builder`.

  An entry is evicted from the map when the `weighted capacity` exceeds its `maximum weighted capacity` threshold. A `EntryWeigher` determines how many units of capacity that an entry consumes. The default weigher assigns each value a weight of `1` to bound the map by the total number of key-value pairs. A map that holds collections may choose to weigh values by the number of elements in the collection and bound the map by the total number of elements that it contains. A change to a value that modifies its weight requires that an update operation is performed on the map.

  An `EvictionListener` may be supplied for notification when an entry is evicted from the map. This listener is invoked on a caller's thread and will not block other threads from operating on the map. An implementation should be aware that the caller's thread will not expect long execution times or failures as a side effect of the listener being notified. Execution safety and a fast turn around time can be achieved by performing the operation asynchronously, such as by submitting a task to an `ExecutorService`.

  The `concurrency level` determines the number of threads that can concurrently modify the table. Using a significantly higher or lower value than needed can waste space or lead to thread contention, but an estimate within an order of magnitude of the ideal value does not usually have a noticeable impact. Because placement in hash tables is essentially random, the actual concurrency will vary.

  This class and its views and iterators implement all of the optional methods of the `Map` and `Iterator` interfaces.

  Like `Hashtable` but unlike `HashMap`, this class does not allow `null` to be used as a key or value. Unlike `LinkedHashMap`, this class does not provide predictable iteration order. A snapshot of the keys and entries may be obtained in ascending and descending order of retention.

  See Also:
    http://code.google.com/p/concurrentlinkedhashmap/, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ConcurrentLinkedHashMap.Builder<K,V>` A builder that creates `ConcurrentLinkedHashMap` instances.

    - ### Nested classes/interfaces inherited from class java.util.AbstractMap

      `java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>`

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

      `java.util.Map.Entry<K,V>`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Set<K>` | `ascendingKeySet()` Returns a unmodifiable snapshot `Set` view of the keys contained in this map.
    `java.util.Set<K>` | `ascendingKeySetWithLimit(int limit)` Returns an unmodifiable snapshot `Set` view of the keys contained in this map.
    `java.util.Map<K,V>` | `ascendingMap()` Returns an unmodifiable snapshot `Map` view of the mappings contained in this map.
    `java.util.Map<K,V>` | `ascendingMapWithLimit(int limit)` Returns an unmodifiable snapshot `Map` view of the mappings contained in this map.
    `long` | `capacity()` Retrieves the maximum weighted capacity of the map.
    `void` | `clear()`
    `boolean` | `containsKey(java.lang.Object key)`
    `boolean` | `containsValue(java.lang.Object value)`
    `java.util.Set<K>` | `descendingKeySet()` Returns an unmodifiable snapshot `Set` view of the keys contained in this map.
    `java.util.Set<K>` | `descendingKeySetWithLimit(int limit)` Returns an unmodifiable snapshot `Set` view of the keys contained in this map.
    `java.util.Map<K,V>` | `descendingMap()` Returns an unmodifiable snapshot `Map` view of the mappings contained in this map.
    `java.util.Map<K,V>` | `descendingMapWithLimit(int limit)` Returns an unmodifiable snapshot `Map` view of the mappings contained in this map.
    `java.util.Set<java.util.Map.Entry<K,V>>` | `entrySet()`
    `V` | `get(java.lang.Object key)`
    `V` | `getQuietly(java.lang.Object key)` Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
    `boolean` | `isEmpty()`
    `java.util.Set<K>` | `keySet()`
    `V` | `put(K key, V value)`
    `V` | `putIfAbsent(K key, V value)`
    `V` | `remove(java.lang.Object key)`
    `boolean` | `remove(java.lang.Object key, java.lang.Object value)`
    `V` | `replace(K key, V value)`
    `boolean` | `replace(K key, V oldValue, V newValue)`
    `void` | `setCapacity(long capacity)` Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
    `int` | `size()`
    `java.util.Collection<V>` | `values()`
    `long` | `weightedSize()` Returns the weighted size of this map.

    - ### Methods inherited from class java.util.AbstractMap

      `clone, equals, hashCode, putAll, toString`

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

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.concurrent.ConcurrentMap

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll`

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

      `equals, hashCode, putAll`

- - ### Method Detail

    - #### capacity

          public long capacity()

      Retrieves the maximum weighted capacity of the map.
      Returns:
        the maximum weighted capacity

    - #### setCapacity

          public void setCapacity(long capacity)

      Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
      Parameters:
        `capacity` - the maximum weighted capacity of the map
      Throws:
        `java.lang.IllegalArgumentException` - if the capacity is negative

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `java.util.Map<K,V>`
      Overrides:
        `isEmpty` in class `java.util.AbstractMap<K,V>`

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Map<K,V>`
      Overrides:
        `size` in class `java.util.AbstractMap<K,V>`

    - #### weightedSize

          public long weightedSize()

      Returns the weighted size of this map.
      Returns:
        the combined weight of the values in this map

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Map<K,V>`
      Overrides:
        `clear` in class `java.util.AbstractMap<K,V>`

    - #### containsKey

          public boolean containsKey(java.lang.Object key)

      Specified by:
        `containsKey` in interface `java.util.Map<K,V>`
      Overrides:
        `containsKey` in class `java.util.AbstractMap<K,V>`

    - #### containsValue

          public boolean containsValue(java.lang.Object value)

      Specified by:
        `containsValue` in interface `java.util.Map<K,V>`
      Overrides:
        `containsValue` in class `java.util.AbstractMap<K,V>`

    - #### get

          public V get(java.lang.Object key)

      Specified by:
        `get` in interface `java.util.Map<K,V>`
      Overrides:
        `get` in class `java.util.AbstractMap<K,V>`

    - #### getQuietly

          public V getQuietly(java.lang.Object key)

      Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key. This method differs from `get(Object)` in that it does not record the operation with the page replacement policy.
      Parameters:
        `key` - the key whose associated value is to be returned
      Returns:
        the value to which the specified key is mapped, or `null` if this map contains no mapping for the key
      Throws:
        `java.lang.NullPointerException` - if the specified key is null

    - #### put

          public V put(K key,
                       V value)

      Specified by:
        `put` in interface `java.util.Map<K,V>`
      Overrides:
        `put` in class `java.util.AbstractMap<K,V>`

    - #### putIfAbsent

          public V putIfAbsent(K key,
                               V value)

      Specified by:
        `putIfAbsent` in interface `java.util.concurrent.ConcurrentMap<K,V>`
      Specified by:
        `putIfAbsent` in interface `java.util.Map<K,V>`

    - #### remove

          public V remove(java.lang.Object key)

      Specified by:
        `remove` in interface `java.util.Map<K,V>`
      Overrides:
        `remove` in class `java.util.AbstractMap<K,V>`

    - #### remove

          public boolean remove(java.lang.Object key,
                                java.lang.Object value)

      Specified by:
        `remove` in interface `java.util.concurrent.ConcurrentMap<K,V>`
      Specified by:
        `remove` in interface `java.util.Map<K,V>`

    - #### replace

          public V replace(K key,
                           V value)

      Specified by:
        `replace` in interface `java.util.concurrent.ConcurrentMap<K,V>`
      Specified by:
        `replace` in interface `java.util.Map<K,V>`

    - #### replace

          public boolean replace(K key,
                                 V oldValue,
                                 V newValue)

      Specified by:
        `replace` in interface `java.util.concurrent.ConcurrentMap<K,V>`
      Specified by:
        `replace` in interface `java.util.Map<K,V>`

    - #### keySet

          public java.util.Set<K> keySet()

      Specified by:
        `keySet` in interface `java.util.Map<K,V>`
      Overrides:
        `keySet` in class `java.util.AbstractMap<K,V>`

    - #### ascendingKeySet

          public java.util.Set<K> ascendingKeySet()

      Returns a unmodifiable snapshot `Set` view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

      Beware that, unlike in `keySet()`, obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

      Returns:
        an ascending snapshot view of the keys in this map

    - #### ascendingKeySetWithLimit

          public java.util.Set<K> ascendingKeySetWithLimit(int limit)

      Returns an unmodifiable snapshot `Set` view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

      Beware that, unlike in `keySet()`, obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

      Parameters:
        `limit` - the maximum size of the returned set
      Returns:
        a ascending snapshot view of the keys in this map
      Throws:
        `java.lang.IllegalArgumentException` - if the limit is negative

    - #### descendingKeySet

          public java.util.Set<K> descendingKeySet()

      Returns an unmodifiable snapshot `Set` view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

      Beware that, unlike in `keySet()`, obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

      Returns:
        a descending snapshot view of the keys in this map

    - #### descendingKeySetWithLimit

          public java.util.Set<K> descendingKeySetWithLimit(int limit)

      Returns an unmodifiable snapshot `Set` view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

      Beware that, unlike in `keySet()`, obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

      Parameters:
        `limit` - the maximum size of the returned set
      Returns:
        a descending snapshot view of the keys in this map
      Throws:
        `java.lang.IllegalArgumentException` - if the limit is negative

    - #### values

          public java.util.Collection<V> values()

      Specified by:
        `values` in interface `java.util.Map<K,V>`
      Overrides:
        `values` in class `java.util.AbstractMap<K,V>`

    - #### entrySet

          public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

      Specified by:
        `entrySet` in interface `java.util.Map<K,V>`
      Specified by:
        `entrySet` in class `java.util.AbstractMap<K,V>`

    - #### ascendingMap

          public java.util.Map<K,V> ascendingMap()

      Returns an unmodifiable snapshot `Map` view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

      Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

      Returns:
        a ascending snapshot view of this map

    - #### ascendingMapWithLimit

          public java.util.Map<K,V> ascendingMapWithLimit(int limit)

      Returns an unmodifiable snapshot `Map` view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

      Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

      Parameters:
        `limit` - the maximum size of the returned map
      Returns:
        a ascending snapshot view of this map
      Throws:
        `java.lang.IllegalArgumentException` - if the limit is negative

    - #### descendingMap

          public java.util.Map<K,V> descendingMap()

      Returns an unmodifiable snapshot `Map` view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

      Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

      Returns:
        a descending snapshot view of this map

    - #### descendingMapWithLimit

          public java.util.Map<K,V> descendingMapWithLimit(int limit)

      Returns an unmodifiable snapshot `Map` view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

      Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

      Parameters:
        `limit` - the maximum size of the returned map
      Returns:
        a descending snapshot view of this map
      Throws:
        `java.lang.IllegalArgumentException` - if the limit is negative