Package org.apache.ofbiz.base.util.cache

Class UtilCache<K,​V>

  • All Implemented Interfaces:
    com.googlecode.concurrentlinkedhashmap.EvictionListener<java.lang.Object,​CacheLine<V>>, java.io.Serializable
    public class UtilCache<K,​V>
extends java.lang.Object
implements java.io.Serializable, com.googlecode.concurrentlinkedhashmap.EvictionListener<java.lang.Object,​CacheLine<V>>
    Generalized caching utility. Provides a number of caching features:
    • Limited or unlimited element capacity
    • If limited, removes elements with the LRU (Least Recently Used) algorithm
    • Keeps track of when each element was loaded into the cache
    • Using the expireTime can report whether a given element has expired
    • Counts misses and hits
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected long expireTimeNanos
      Specifies the amount of time since initial loading before an element will be reported as expired.
      protected java.util.concurrent.atomic.AtomicLong hitCount
      A count of the number of cache hits
      protected java.util.Set<CacheListener<K,​V>> listeners
      The set of listeners to receive notifications when items are modified (either deliberately or because they were expired).
      protected int maxInMemory  
      protected java.util.concurrent.ConcurrentMap<java.lang.Object,​CacheLine<V>> memoryTable  
      protected java.util.concurrent.atomic.AtomicLong missCountExpired
      A count of the number of cache misses because it expired
      protected java.util.concurrent.atomic.AtomicLong missCountNotFound
      A count of the number of cache misses because it is not found in the cache
      protected java.util.concurrent.atomic.AtomicLong missCountSoftRef
      A count of the number of cache misses because it was cleared from the Soft Reference (ie garbage collection, etc)
      static java.lang.String module  
      protected java.util.concurrent.atomic.AtomicLong removeHitCount
      A count of the number of cache hits on removes
      protected java.util.concurrent.atomic.AtomicLong removeMissCount
      A count of the number of cache misses on removes
      protected int sizeLimit
      The maximum number of elements in the cache.
      protected boolean useSoftReference
      Specifies whether or not to use soft references for this cache, defaults to false

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListener​(CacheListener<K,​V> listener)
      Adds an event listener for key removals
      void clear()  
      static void clearAllCaches()
      Removes all elements from this cache
      static void clearCache​(java.lang.String cacheName)  
      static void clearCachesThatStartWith​(java.lang.String startsWith)  
      void clearCounters()
      Clears the hit and miss counters
      boolean containsKey​(java.lang.Object key)
      Returns a boolean specifying whether or not an element with the specified key is in the cache.
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache()  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(int sizeLimit, long expireTime)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name, boolean useSoftReference)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name, int sizeLimit, int maxInMemory, long expireTime, boolean useSoftReference)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name, int sizeLimit, int maxInMemory, long expireTime, boolean useSoftReference, java.lang.String... names)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name, int sizeLimit, long expireTime)  
      static <K,​V>
      UtilCache<K,​V>      		 createUtilCache​(java.lang.String name, int sizeLimit, long expireTime, boolean useSoftReference)  
      void erase()
      Removes all elements from this cache
      static <K,​V>
      UtilCache<K,​V>      		 findCache​(java.lang.String cacheName)  
      V get​(java.lang.Object key)
      Gets an element from the cache according to the specified key.
      java.util.Set<? extends K> getCacheLineKeys()
      NOTE: this returns an unmodifiable copy of the keySet, so removing from here won't have an effect, and calling a remove while iterating through the set will not cause a concurrent modification exception.
      java.lang.Object getCacheLineTable()  
      java.util.Collection<? extends CacheLine<V>> getCacheLineValues()  
      long getExpireTime()
      return the current expire time for the cache elements
      long getHitCount()
      Returns the number of successful hits on the cache
      java.util.Collection<? extends java.util.Map<java.lang.String,​java.lang.Object>> getLineInfos()  
      int getMaxInMemory()  
      long getMissCountExpired()
      Returns the number of cache misses from entries that are expired
      long getMissCountNotFound()
      Returns the number of cache misses from entries that are not found in the cache
      long getMissCountSoftRef()
      Returns the number of cache misses from entries that are have had the soft reference cleared out (by garbage collector and such)
      long getMissCountTotal()
      Returns the number of cache misses caused by any reason
      java.lang.String getName()
      Getter for the name of the UtilCache instance.
      static <K,​V>
      UtilCache<K,​V>      		 getOrCreateUtilCache​(java.lang.String name, int sizeLimit, int maxInMemory, long expireTime, boolean useSoftReference, java.lang.String... names)  
      static java.lang.String getPropertyParam​(java.util.ResourceBundle res, java.lang.String[] propNames, java.lang.String parameter)  
      long getRemoveHitCount()  
      long getRemoveMissCount()  
      long getSizeInBytes()  
      int getSizeLimit()  
      boolean getUseSoftReference()
      Return whether or not the cache lines should use a soft reference to the data
      static java.util.Set<java.lang.String> getUtilCacheTableKeySet()  
      boolean isEmpty()  
      protected void noteAddition​(K key, V newValue)
      Send a key addition event to all registered listeners
      protected void noteRemoval​(K key, V oldValue)
      Send a key removal event to all registered listeners
      protected void noteUpdate​(K key, V newValue, V oldValue)
      Send a key update event to all registered listeners
      void onEviction​(java.lang.Object key, CacheLine<V> value)  
      V put​(K key, V value)
      Puts or loads the passed element into the cache
      V put​(K key, V value, long expireTimeMillis)
      Puts or loads the passed element into the cache
      V putIfAbsent​(K key, V value)  
      V putIfAbsent​(K key, V value, long expireTimeMillis)  
      V putIfAbsentAndGet​(K key, V value)  
      V remove​(java.lang.Object key)
      Removes an element from the cache according to the specified key
      protected V removeInternal​(java.lang.Object key, boolean countRemove)
      This is used for internal remove calls because we only want to count external calls
      protected void removeInternal​(java.lang.Object key, CacheLine<V> existingCacheLine)  
      void removeListener​(CacheListener<K,​V> listener)
      Removes an event listener for key removals
      void setExpireTime​(long expireTimeMillis)
      Sets the expire time for the cache elements.
      void setMaxInMemory​(int newInMemory)  
      protected void setPropertiesParams​(java.lang.String cacheName)  
      void setPropertiesParams​(java.lang.String[] propNames)  
      void setPropertiesParams​(java.lang.String settingsResourceName, java.lang.String[] propNames)  
      void setSizeLimit​(int newSizeLimit)  
      void setUseSoftReference​(boolean useSoftReference)
      Set whether or not the cache lines should use a soft reference to the data
      int size()
      Returns the number of elements currently in the cache
      static boolean validKey​(java.lang.String cacheName, java.lang.Object key)
      Checks for a non-expired key in a specific cache
      java.util.Collection<V> values()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • module

        public static final java.lang.String module

      • hitCount

        protected java.util.concurrent.atomic.AtomicLong hitCount
        A count of the number of cache hits

      • missCountNotFound

        protected java.util.concurrent.atomic.AtomicLong missCountNotFound
        A count of the number of cache misses because it is not found in the cache

      • missCountExpired

        protected java.util.concurrent.atomic.AtomicLong missCountExpired
        A count of the number of cache misses because it expired

      • missCountSoftRef

        protected java.util.concurrent.atomic.AtomicLong missCountSoftRef
        A count of the number of cache misses because it was cleared from the Soft Reference (ie garbage collection, etc)

      • removeHitCount

        protected java.util.concurrent.atomic.AtomicLong removeHitCount
        A count of the number of cache hits on removes

      • removeMissCount

        protected java.util.concurrent.atomic.AtomicLong removeMissCount
        A count of the number of cache misses on removes

      • sizeLimit

        protected int sizeLimit
        The maximum number of elements in the cache. If set to 0, there will be no limit on the number of elements in the cache.

      • maxInMemory

        protected int maxInMemory

      • expireTimeNanos

        protected long expireTimeNanos
        Specifies the amount of time since initial loading before an element will be reported as expired. If set to 0, elements will never expire.

      • useSoftReference

        protected boolean useSoftReference
        Specifies whether or not to use soft references for this cache, defaults to false

      • listeners

        protected java.util.Set<CacheListener<K,​V>> listeners
        The set of listeners to receive notifications when items are modified (either deliberately or because they were expired).

      • memoryTable

        protected java.util.concurrent.ConcurrentMap<java.lang.Object,​CacheLine<V>> memoryTable

    • Method Detail

      • getPropertyParam

        public static java.lang.String getPropertyParam​(java.util.ResourceBundle res,
                                                java.lang.String[] propNames,
                                                java.lang.String parameter)

      • setPropertiesParams

        protected void setPropertiesParams​(java.lang.String cacheName)

      • setPropertiesParams

        public void setPropertiesParams​(java.lang.String[] propNames)

      • setPropertiesParams

        public void setPropertiesParams​(java.lang.String settingsResourceName,
                                java.lang.String[] propNames)

      • getCacheLineTable

        public java.lang.Object getCacheLineTable()

      • isEmpty

        public boolean isEmpty()

      • put

        public V put​(K key,
             V value)
        Puts or loads the passed element into the cache
        Parameters:
        key - The key for the element, used to reference it in the hashtables and LRU linked list
        value - The value of the element

      • putIfAbsent

        public V putIfAbsent​(K key,
                     V value)

      • putIfAbsentAndGet

        public V putIfAbsentAndGet​(K key,
                           V value)

      • put

        public V put​(K key,
             V value,
             long expireTimeMillis)
        Puts or loads the passed element into the cache
        Parameters:
        key - The key for the element, used to reference it in the hashtables and LRU linked list
        value - The value of the element
        expireTimeMillis - how long to keep this key in the cache

      • putIfAbsent

        public V putIfAbsent​(K key,
                     V value,
                     long expireTimeMillis)

      • get

        public V get​(java.lang.Object key)
        Gets an element from the cache according to the specified key.
        Parameters:
        key - The key for the element, used to reference it in the hashtables and LRU linked list
        Returns:
        The value of the element specified by the key

      • values

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

      • getSizeInBytes

        public long getSizeInBytes()

      • remove

        public V remove​(java.lang.Object key)
        Removes an element from the cache according to the specified key
        Parameters:
        key - The key for the element, used to reference it in the hashtables and LRU linked list
        Returns:
        The value of the removed element specified by the key

      • removeInternal

        protected V removeInternal​(java.lang.Object key,
                           boolean countRemove)
        This is used for internal remove calls because we only want to count external calls

      • removeInternal

        protected void removeInternal​(java.lang.Object key,
                              CacheLine<V> existingCacheLine)

      • erase

        public void erase()
        Removes all elements from this cache

      • clear

        public void clear()

      • clearAllCaches

        public static void clearAllCaches()
        Removes all elements from this cache

      • getUtilCacheTableKeySet

        public static java.util.Set<java.lang.String> getUtilCacheTableKeySet()

      • getName

        public java.lang.String getName()
        Getter for the name of the UtilCache instance.
        Returns:
        The name of the instance

      • getHitCount

        public long getHitCount()
        Returns the number of successful hits on the cache
        Returns:
        The number of successful cache hits

      • getMissCountNotFound

        public long getMissCountNotFound()
        Returns the number of cache misses from entries that are not found in the cache
        Returns:
        The number of cache misses

      • getMissCountExpired

        public long getMissCountExpired()
        Returns the number of cache misses from entries that are expired
        Returns:
        The number of cache misses

      • getMissCountSoftRef

        public long getMissCountSoftRef()
        Returns the number of cache misses from entries that are have had the soft reference cleared out (by garbage collector and such)
        Returns:
        The number of cache misses

      • getMissCountTotal

        public long getMissCountTotal()
        Returns the number of cache misses caused by any reason
        Returns:
        The number of cache misses

      • getRemoveHitCount

        public long getRemoveHitCount()

      • getRemoveMissCount

        public long getRemoveMissCount()

      • clearCounters

        public void clearCounters()
        Clears the hit and miss counters

      • setMaxInMemory

        public void setMaxInMemory​(int newInMemory)

      • getMaxInMemory

        public int getMaxInMemory()

      • setSizeLimit

        public void setSizeLimit​(int newSizeLimit)

      • getSizeLimit

        public int getSizeLimit()

      • setExpireTime

        public void setExpireTime​(long expireTimeMillis)
        Sets the expire time for the cache elements. If 0, elements never expire.
        Parameters:
        expireTimeMillis - The expire time for the cache elements

      • getExpireTime

        public long getExpireTime()
        return the current expire time for the cache elements
        Returns:
        The expire time for the cache elements

      • setUseSoftReference

        public void setUseSoftReference​(boolean useSoftReference)
        Set whether or not the cache lines should use a soft reference to the data

      • getUseSoftReference

        public boolean getUseSoftReference()
        Return whether or not the cache lines should use a soft reference to the data

      • size

        public int size()
        Returns the number of elements currently in the cache
        Returns:
        The number of elements currently in the cache

      • containsKey

        public boolean containsKey​(java.lang.Object key)
        Returns a boolean specifying whether or not an element with the specified key is in the cache.
        Parameters:
        key - The key for the element, used to reference it in the hashtables and LRU linked list
        Returns:
        True is the cache contains an element corresponding to the specified key, otherwise false

      • getCacheLineKeys

        public java.util.Set<? extends K> getCacheLineKeys()
        NOTE: this returns an unmodifiable copy of the keySet, so removing from here won't have an effect, and calling a remove while iterating through the set will not cause a concurrent modification exception. This behavior is necessary for now for the persisted cache feature.

      • getCacheLineValues

        public java.util.Collection<? extends CacheLine<V>> getCacheLineValues()

      • getLineInfos

        public java.util.Collection<? extends java.util.Map<java.lang.String,​java.lang.Object>> getLineInfos()

      • noteAddition

        protected void noteAddition​(K key,
                            V newValue)
        Send a key addition event to all registered listeners

      • noteRemoval

        protected void noteRemoval​(K key,
                           V oldValue)
        Send a key removal event to all registered listeners

      • noteUpdate

        protected void noteUpdate​(K key,
                          V newValue,
                          V oldValue)
        Send a key update event to all registered listeners

      • addListener

        public void addListener​(CacheListener<K,​V> listener)
        Adds an event listener for key removals

      • removeListener

        public void removeListener​(CacheListener<K,​V> listener)
        Removes an event listener for key removals

      • validKey

        public static boolean validKey​(java.lang.String cacheName,
                               java.lang.Object key)
        Checks for a non-expired key in a specific cache

      • clearCachesThatStartWith

        public static void clearCachesThatStartWith​(java.lang.String startsWith)

      • clearCache

        public static void clearCache​(java.lang.String cacheName)

      • getOrCreateUtilCache

        public static <K,​V> UtilCache<K,​V> getOrCreateUtilCache​(java.lang.String name,
                                                                    int sizeLimit,
                                                                    int maxInMemory,
                                                                    long expireTime,
                                                                    boolean useSoftReference,
                                                                    java.lang.String... names)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name,
                                                               int sizeLimit,
                                                               int maxInMemory,
                                                               long expireTime,
                                                               boolean useSoftReference,
                                                               java.lang.String... names)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name,
                                                               int sizeLimit,
                                                               int maxInMemory,
                                                               long expireTime,
                                                               boolean useSoftReference)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name,
                                                               int sizeLimit,
                                                               long expireTime,
                                                               boolean useSoftReference)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name,
                                                               int sizeLimit,
                                                               long expireTime)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(int sizeLimit,
                                                               long expireTime)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name,
                                                               boolean useSoftReference)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache​(java.lang.String name)

      • createUtilCache

        public static <K,​V> UtilCache<K,​V> createUtilCache()

      • findCache

        public static <K,​V> UtilCache<K,​V> findCache​(java.lang.String cacheName)

      • onEviction

        public void onEviction​(java.lang.Object key,
                       CacheLine<V> value)
        Specified by:
        onEviction in interface com.googlecode.concurrentlinkedhashmap.EvictionListener<K,​V>