Package org.zkoss.util

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

    • 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

    • 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

      • 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