Package org.zkoss.util

## Class CacheMap<K,​V>

- java.lang.Object
- - org.zkoss.util.CacheMap<K,​V>

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `java.util.Map<K,​V>`, `Cache<K,​V>`
  Direct Known Subclasses:
    `ResourceCache`

      public class CacheMap<K,​V>
      extends java.lang.Object
      implements java.util.Map<K,​V>, Cache<K,​V>, java.io.Serializable, java.lang.Cloneable

  The cache map. The key-to-value mappings hold in this map is temporary. They are removed when GC demanding memory and a criteria is met. The criteria is whether the mapping is old enough (called lifetime), or the upper bound is hit (called max-size).

  The criteria can be changed by overriding `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)`. When to check the criteria can be changed by overriding `shallExpunge()`.

  If the criteria is totally independent of GC, you could override `shallExpunge()` to always return true (rather than when GC is activated).

  It is different from WeakHashMap:

  - The mapping might be removed even if the key is hold somewhere (i.e., strong reachable).
  - The mapping might not be removed when GC demanding memory if the criteria doesn't meet.
  - It is not serializable.

  Like other maps, it is not thread-safe. To get one, use java.util.Collections.synchronizedMap.

  Implementation Note: there is another version of CacheMap that uses WeakReference for each value (refer to obsolete). The drawback is that all mapping will be queued and need to be examined, because GC tends to release all reference at once.

  We don't use PhantomReference because it is still required to re-create the reference after enqueued.

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `CacheMap.Value<V>` | The class to hold key/value.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static int` | `EXPUNGE_CONTINUE` | Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote the searching of the next mapping shall continue.
    `protected static int` | `EXPUNGE_NO` | Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote it shall not be expunged.
    `protected static int` | `EXPUNGE_STOP` | Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote the searching of the next mapping shall stop.
    `protected static int` | `EXPUNGE_YES` | Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote it shall be expunged.

    - ### Fields inherited from interface org.zkoss.util.Cache

      `DEFAULT_LIFETIME, DEFAULT_MAX_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CacheMap()` | Constructs a cache map.
    `CacheMap​(boolean accessOrder)` | Constructs a cache map.
    `CacheMap​(int cap)` | Constructs a cache map.
    `CacheMap​(int cap, float load)` | Constructs a cache map.
    `CacheMap​(int cap, float load, boolean accessOrder)` | Constructs a cache map.
    `CacheMap​(int maxSize, int lifetime)` | Constructs a cache map with the specified max size and lifetime.
    `CacheMap​(int maxSize, int lifetime, boolean accessOrder)` | Constructs a cache map with the specified max size and lifetime.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected int` | `canExpunge​(int size, CacheMap.Value<V> v)` | Tests whether certain value is OK to expunge.
    `void` | `clear()` | Clears all objects being cached.
    `java.lang.Object` | `clone()` |
    `boolean` | `containsKey​(java.lang.Object key)` | Returns whether the specified key is stored.
    `boolean` | `containsKeyWithoutExpunge​(java.lang.Object key)` | Tests if the given key exists without trying to expunge for more memory.
    `boolean` | `containsValue​(java.lang.Object value)` |
    `java.util.Set<java.util.Map.Entry<K,​V>>` | `entrySet()` |
    `boolean` | `equals​(java.lang.Object o)` |
    `int` | `expunge()` | Enforces to expunge items that exceeds the maximal allowed number or lifetime.
    `V` | `get​(java.lang.Object key)` | Returns the object of the specified key, or null if not found.
    `int` | `getLifetime()` | Gets the minimal lifetime, unit=milliseconds.
    `int` | `getMaxSize()` | Gets the maximal allowed size.
    `V` | `getWithoutExpunge​(java.lang.Object key)` | Returns the value without trying to expunge for more memory.
    `int` | `hashCode()` |
    `boolean` | `isEmpty()` |
    `boolean` | `isEmptyWithoutExpunge()` | Returns whether it is empty without trying to expunge first.
    `java.util.Set<K>` | `keySet()` |
    `protected void` | `onExpunge​(CacheMap.Value<V> v)` | Called when a pair of key and value having been expunged.
    `V` | `put​(K key, V value)` | Stores an object to the cache.
    `void` | `putAll​(java.util.Map<? extends K,​? extends V> map)` |
    `V` | `remove​(java.lang.Object key)` | Removes an object from the cache.
    `void` | `setLifetime​(int lifetime)` | Sets the minimal lifetime.
    `void` | `setMaxSize​(int maxsize)` | Sets the maximal allowed size.
    `protected boolean` | `shallExpunge()` | Returns whether it is time to expunge.
    `int` | `size()` |
    `int` | `sizeWithoutExpunge()` | Returns the size without trying to expunge first.
    `java.lang.String` | `toString()` |
    `java.util.Collection<V>` | `values()` |

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

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

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

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

- - ### Field Detail

    - #### EXPUNGE_NO

          protected static final int EXPUNGE_NO

      Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote it shall not be expunged.
      See Also:
        Constant Field Values

    - #### EXPUNGE_YES

          protected static final int EXPUNGE_YES

      Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote it shall be expunged.
      See Also:
        Constant Field Values

    - #### EXPUNGE_CONTINUE

          protected static final int EXPUNGE_CONTINUE

      Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote the searching of the next mapping shall continue.
      See Also:
        Constant Field Values

    - #### EXPUNGE_STOP

          protected static final int EXPUNGE_STOP

      Returns by `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` to denote the searching of the next mapping shall stop.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CacheMap

          public CacheMap​(int maxSize,
                          int lifetime)

      Constructs a cache map with the specified max size and lifetime. Unlike LinkedHashMap, the default order is the access order, i.e., the order is changed once accessed, including get().
      Since:
        3.0.0

    - #### CacheMap

          public CacheMap()

      Constructs a cache map. Unlike LinkedHashMap, the default order is the access order, i.e., the order is changed once accessed, including get().

    - #### CacheMap

          public CacheMap​(int cap)

      Constructs a cache map. Unlike LinkedHashMap, the default order is the access order, i.e., the order is changed once accessed, including get().

    - #### CacheMap

          public CacheMap​(int cap,
                          float load)

      Constructs a cache map. Unlike LinkedHashMap, the default order is the access order, i.e., the order is changed once accessed, including get().

    - #### CacheMap

          public CacheMap​(boolean accessOrder)

      Constructs a cache map.
      Parameters:
        `accessOrder` - whether to use the access order. Specify false for the insertion order.
      Since:
        6.0.0

    - #### CacheMap

          public CacheMap​(int maxSize,
                          int lifetime,
                          boolean accessOrder)

      Constructs a cache map with the specified max size and lifetime.
      Parameters:
        `accessOrder` - whether to use the access order. Specify false for the insertion order.
      Since:
        6.0.0

    - #### CacheMap

          public CacheMap​(int cap,
                          float load,
                          boolean accessOrder)

      Constructs a cache map.
      Parameters:
        `accessOrder` - whether to use the access order. Specify false for the insertion order.
      Since:
        6.0.0

  - ### Method Detail

    - #### onExpunge

          protected void onExpunge​(CacheMap.Value<V> v)

      Called when a pair of key and value having been expunged. This method is called after it is removed, so you could add it back.

      Default: does nothing

    - #### shallExpunge

          protected boolean shallExpunge()

      Returns whether it is time to expunge. Once shallExpunge returns true, values are examined one-by-one thru `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)`, and expunged if EXPUNGE_YES.

      This implementation returns true only if GC was activated. You might override it to return true, such that expunge is enforced no matter GC was activated.

      See Also:
        `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)`

    - #### canExpunge

          protected int canExpunge​(int size,
                                   CacheMap.Value<V> v)

      Tests whether certain value is OK to expunge.

      Note: values are tested thru `canExpunge(int, org.zkoss.util.CacheMap.Value<V>)` only if `shallExpunge()` returns true.

      Deriving classes might override this method to return different value for different criteria.

      The return value could be a combination of EXPUNGE_xxx. One of EXPUNGE_YES and EXPUNGE_NO is returned to denote whether to expunge the mapping. One of EXPUNGE_CONTINUE and EXPUNGE_STOP is returned to denote whether to continue the searching of the next mapping for expunging.

      Normally, you return either (EXPUNGE_YES|EXPUNGE_CONTINUE) or (EXPUNG_NO|EXPUNGE_STOP). Notice that the mapping is queried in the last-access order. Thus, you rarely needs to return (EXPUNGE_NO|EXPUNGE_CONTINUE) unless the appropriate one might be out of this order.

      This implementation compares the access time and size. It returns (EXPUNGE_YES|EXPUNGE_CONTINUE) if OK, and (EXPUNGE_NO|EXPUNGE_STOP) if not.

      Parameters:
        `size` - the current size. It is used instead of size(), since the entry might not be removed yet (such as `FastReadCache`).
      Returns:
        a combination of EXPUNGE_xxx
      See Also:
        `shallExpunge()`

    - #### expunge

          public int expunge()

      Enforces to expunge items that exceeds the maximal allowed number or lifetime.

      By default, this method is called only GC takes places.

      Returns:
        number of items left (`size()`) after expunged
      Since:
        3.6.1

    - #### getLifetime

          public int getLifetime()

      Gets the minimal lifetime, unit=milliseconds. An mapping won't be removed by GC unless the minimal lifetime or the maximal allowed size exceeds.
      Specified by:
        `getLifetime` in interface `Cache<K,​V>`
      See Also:
        `getMaxSize()`

    - #### setLifetime

          public void setLifetime​(int lifetime)

      Sets the minimal lifetime. Default: `Cache.DEFAULT_LIFETIME`.
      Specified by:
        `setLifetime` in interface `Cache<K,​V>`
      Parameters:
        `lifetime` - the lifetime, unit=milliseconds; if non-positive, they will be removed immediately.
      See Also:
        `getLifetime()`

    - #### getMaxSize

          public int getMaxSize()

      Gets the maximal allowed size. Default: `Cache.DEFAULT_MAX_SIZE`. An mapping won't be removed by GC unless the minimal lifetime or the maximal allowed size exceeds.

      Notice: getMaxSize() is only a soft limit. It takes effect only if GC takes place.

      Specified by:
        `getMaxSize` in interface `Cache<K,​V>`
      See Also:
        `getLifetime()`

    - #### setMaxSize

          public void setMaxSize​(int maxsize)

      Sets the maximal allowed size.
      Specified by:
        `setMaxSize` in interface `Cache<K,​V>`
      See Also:
        `getMaxSize()`

    - #### isEmpty

          public boolean isEmpty()

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

    - #### isEmptyWithoutExpunge

          public boolean isEmptyWithoutExpunge()

      Returns whether it is empty without trying to expunge first.
      Since:
        3.0.1

    - #### size

          public int size()

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

    - #### sizeWithoutExpunge

          public int sizeWithoutExpunge()

      Returns the size without trying to expunge first.
      Since:
        3.0.1

    - #### clear

          public void clear()

      Description copied from interface: `Cache`
      Clears all objects being cached.
      Specified by:
        `clear` in interface `Cache<K,​V>`
      Specified by:
        `clear` in interface `java.util.Map<K,​V>`

    - #### remove

          public V remove​(java.lang.Object key)

      Description copied from interface: `Cache`
      Removes an object from the cache.
      Specified by:
        `remove` in interface `Cache<K,​V>`
      Specified by:
        `remove` in interface `java.util.Map<K,​V>`
      Returns:
        the object if found.

    - #### get

          public V get​(java.lang.Object key)

      Description copied from interface: `Cache`
      Returns the object of the specified key, or null if not found.
      Specified by:
        `get` in interface `Cache<K,​V>`
      Specified by:
        `get` in interface `java.util.Map<K,​V>`

    - #### getWithoutExpunge

          public V getWithoutExpunge​(java.lang.Object key)

      Returns the value without trying to expunge for more memory. It is useful if you want to preserve all entries.

    - #### containsKey

          public boolean containsKey​(java.lang.Object key)

      Description copied from interface: `Cache`
      Returns whether the specified key is stored.
      Specified by:
        `containsKey` in interface `Cache<K,​V>`
      Specified by:
        `containsKey` in interface `java.util.Map<K,​V>`

    - #### containsKeyWithoutExpunge

          public boolean containsKeyWithoutExpunge​(java.lang.Object key)

      Tests if the given key exists without trying to expunge for more memory.

    - #### containsValue

          public boolean containsValue​(java.lang.Object value)

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

    - #### put

          public V put​(K key,
                       V value)

      Description copied from interface: `Cache`
      Stores an object to the cache.
      Specified by:
        `put` in interface `Cache<K,​V>`
      Specified by:
        `put` in interface `java.util.Map<K,​V>`
      Returns:
        the previous value of the same, or null if no such value

    - #### putAll

          public void putAll​(java.util.Map<? extends K,​? extends V> map)

      Specified by:
        `putAll` in interface `java.util.Map<K,​V>`

    - #### entrySet

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

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

    - #### keySet

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

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

    - #### values

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

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

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Map<K,​V>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals​(java.lang.Object o)

      Specified by:
        `equals` in interface `java.util.Map<K,​V>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### clone

          public java.lang.Object clone()

      Overrides:
        `clone` in class `java.lang.Object`