Package com.tangosol.net.cache

Class CachingMap<K,​V>

  • All Implemented Interfaces:
    Map<K,​V>
    Direct Known Subclasses:
    NearCache
    public class CachingMap<K,​V>
extends Object
implements Map<K,​V>
    Map implementation that wraps two maps - a front map (assumed to be "inexpensive" and probably "incomplete") and a back map (assumed to be "complete" and "correct", but more "expensive") - using a read-through/write-through approach.

    If the back map implements ObservableMap interface, the CachingMap provides four different strategies of invalidating the front map entries that have changed by other processes in the back map:

    • LISTEN_NONE strategy instructs the cache not to listen for invalidation events at all. This is the best choice for raw performance and scalability when business requirements permit the use of data which might not be absolutely current. Freshness of data can be guaranteed by use of a sufficiently brief eviction policy for the front map;
    • LISTEN_PRESENT strategy instructs the CachingMap to listen to the back map events related only to the items currently present in the front map. This strategy works best when each instance of a front map contains distinct subset of data relative to the other front map instances (e.g. sticky data access patterns);
    • LISTEN_ALL strategy instructs the CachingMap to listen to all back map events. This strategy is optimal for read-heavy tiered access patterns where there is significant overlap between the different instances of front maps;
    • LISTEN_AUTO strategy instructs the CachingMap implementation to switch automatically between LISTEN_PRESENT and LISTEN_ALL strategies based on the cache statistics;
    • LISTEN_LOGICAL strategy instructs the CachingMap to listen to all back map events that are not synthetic deletes. A synthetic event could be emitted as a result of eviction or expiration. With this invalidation strategy, it is possible for the front map to contain cache entries that have been synthetically removed from the back (though any subsequent re-insertion will cause the corresponding entries in the front map to be invalidated).

    The front map implementation is assumed to be thread safe; additionally any modifications to the front map are allowed only after the corresponding lock is acquired against the ControlMap.

    Note: null values are not cached in the front map and therefore this implementation is not optimized for maps that allow null values to be stored.

    Author:
    ag/gg 2002.09.10, gg 2003.10.16

    • Field Detail

      • LISTEN_NONE

        public static final int LISTEN_NONE
        No invalidation strategy.
        See Also:
        Constant Field Values

      • LISTEN_PRESENT

        public static final int LISTEN_PRESENT
        Invalidation strategy that instructs the CachingMap to listen to the back map events related only to the items currently present in the front map; this strategy serves best when the changes to the back map come mostly from the CachingMap itself.
        See Also:
        Constant Field Values

      • LISTEN_ALL

        public static final int LISTEN_ALL
        Invalidation strategy that instructs the CachingMap to listen to all back map events; this strategy is preferred when updates to the back map are frequent and with high probability come from the outside of this CachingMap; for example multiple CachingMap instances using the same back map with a large degree of key set overlap between front maps.
        See Also:
        Constant Field Values

      • LISTEN_AUTO

        public static final int LISTEN_AUTO
        Invalidation strategy that instructs the CachingMap implementation to switch automatically between LISTEN_PRESENT and LISTEN_ALL strategies based on the cache statistics.
        See Also:
        Constant Field Values

      • LISTEN_LOGICAL

        public static final int LISTEN_LOGICAL
        Invalidation strategy that instructs the CachingMap to listen to all back map events that are not synthetic deletes. A synthetic event could be emitted as a result of eviction or expiration. With this invalidation strategy, it is possible for the front map to contain cache entries that have been synthetically removed from the back (though any subsequent re-insertion will cause the corresponding entries in the front map to be invalidated).
        See Also:
        Constant Field Values

      • m_nStrategyTarget

        protected int m_nStrategyTarget
        The invalidation strategy that this map is to use.

      • m_nStrategyCurrent

        protected int m_nStrategyCurrent
        The current invalidation strategy, which at times could be different from the target strategy.

      • m_listenerDeactivation

        protected com.tangosol.internal.net.NamedCacheDeactivationListener m_listenerDeactivation
        The NamedCache deactivation listener.

    • Constructor Detail

      • CachingMap

        public CachingMap​(Map<K,​V> mapFront,
                  Map<K,​V> mapBack)
        Construct a CachingMap using two specified maps:
        • FrontMap (aka "cache", "near" or "shallow") and
        • BackMap (aka "actual", "real" or "deep").
        If the BackMap implements the ObservableMap interface a listener will be added to the BackMap to invalidate FrontMap items updated [externally] in the back map using the LISTEN_AUTO strategy.
        Parameters:
        mapBack - back map
        mapFront - front map
        See Also:
        SeppukuMapListener

      • CachingMap

        public CachingMap​(Map<K,​V> mapFront,
                  Map<K,​V> mapBack,
                  int nStrategy)
        Construct a CachingMap using two specified maps:
        • FrontMap (aka "cache", "near" or "shallow") and
        • BackMap (aka "actual", "real" or "deep")
        and using the specified front map invalidation strategy.
        Parameters:
        mapFront - front map
        mapBack - back map
        nStrategy - specifies the strategy used for the front map invalidation; valid values are LISTEN_* constants

    • Method Detail

      • release

        public void release()
        Release the CachingMap. If the BackMap implements an ObservableMap calling this method is necessary to remove the BackMap listener. Any access to the CachingMap which has been released will cause IllegalStateException.

      • getFrontMap

        public Map<K,​V> getFrontMap()
        Obtain the front map reference.

        Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.

        Returns:
        the front Map

      • getBackMap

        public Map<K,​V> getBackMap()
        Obtain the back map reference.

        Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.

        Returns:
        the back Map

      • getInvalidationStrategy

        public int getInvalidationStrategy()
        Obtain the invalidation strategy used by this CachingMap.
        Returns:
        one of LISTEN_* values

      • getControlMap

        public ConcurrentMap getControlMap()
        Obtain the ConcurrentMap that should be used to synchronize the front map modification access.
        Returns:
        a ConcurrentMap controlling the front map modifications

      • isCoherent

        protected boolean isCoherent()
        Determine if changes to the back map affect the front map so that data in the front map stays in sync.
        Returns:
        true if the front map has a means to stay in sync with the back map so that it does not contain stale data

      • getCacheStatistics

        public CacheStatistics getCacheStatistics()
        Obtain the CacheStatistics for this cache.
        Returns:
        a CacheStatistics object

      • clear

        public void clear()
        Clears both the front and back maps.
        Specified by:
        clear in interface Map<K,​V>

      • containsKey

        public boolean containsKey​(Object oKey)
        Specified by:
        containsKey in interface Map<K,​V>

      • containsValue

        public boolean containsValue​(Object oValue)
        Specified by:
        containsValue in interface Map<K,​V>

      • get

        public V get​(Object oKey)
        Specified by:
        get in interface Map<K,​V>

      • getAll

        public Map<K,​V> getAll​(Collection<? extends K> colKeys)
        Get all the specified keys, if they are in the cache. For each key that is in the cache, that key and its corresponding value will be placed in the map that is returned by this method. The absence of a key in the returned map indicates that it was not in the cache, which may imply (for caches that can load behind the scenes) that the requested data could not be loaded.

        Note: this implementation does not differentiate between missing keys or null values stored in the back map; in both cases the returned map will not contain the corresponding entry.

        Parameters:
        colKeys - a collection of keys that may be in the named cache
        Returns:
        a Map of keys to values for the specified keys passed in col
        Since:
        Coherence 2.5

      • getAllFromFrontMap

        protected Map<K,​V> getAllFromFrontMap​(Collection<? extends K> colKeys)
        Retrieve entries from the front map.
        Parameters:
        colKeys - a collection of keys
        Returns:
        a Map of keys to values for a subset of the passed in keys that exist in the front map

      • tryLock

        protected Set<K> tryLock​(Set<K> setKeys)
        Lock the keys in the given set without blocking.
        Parameters:
        setKeys - keys to lock in the control map
        Returns:
        Set of keys that were successfully locked

      • isPriming

        protected boolean isPriming​(MapEvent evt)
        Check if the specified event is a "priming" one.
        Parameters:
        evt - the event
        Returns:
        true if the specified event is a "priming" one

      • isCheckPrimingExclusively

        protected boolean isCheckPrimingExclusively​(boolean fPriming)
        Return true if we can rely on the server emitting priming events (based on receiving a at least one priming event from a storage node).
        Parameters:
        fPriming - whether the event that instigated this check is a priming event
        Returns:
        true if we can rely on the server emitting priming events

      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface Map<K,​V>

      • keySet

        public Set<K> keySet()
        Specified by:
        keySet in interface Map<K,​V>

      • put

        public V put​(K oKey,
             V oValue)
        Specified by:
        put in interface Map<K,​V>

      • put

        public V put​(K oKey,
             V oValue,
             boolean fReturn,
             long cMillis)
        Implementation of put method that optionally skips the return value retrieval and allows to specify an expiry for the cache entry.
        Parameters:
        oKey - the key
        oValue - the value
        fReturn - if true, the return value is required; otherwise the return value will be ignored
        cMillis - the number of milliseconds until the cache entry will expire
        Returns:
        previous value (if required)
        Throws:
        UnsupportedOperationException - if the requested expiry is a positive value and either the front map or the back map implementations do not support the expiration functionality
        See Also:
        CacheMap.put(Object oKey, Object oValue, long cMillis)

      • putAll

        public void putAll​(Map<? extends K,​? extends V> map)
        Specified by:
        putAll in interface Map<K,​V>

      • invalidateFront

        protected void invalidateFront​(Object oKey)
        Invalidate the key from the front. The caller must have the key locked.
        Parameters:
        oKey - the key to invalidate

      • validate

        protected void validate​(MapEvent evt)
        Validate the front map entry for the specified back map event.
        Parameters:
        evt - the MapEvent from the back map

      • remove

        public V remove​(Object oKey)
        Specified by:
        remove in interface Map<K,​V>

      • size

        public int size()
        Return the number of key-value mappings in this map. Expensive: always reflects the contents of the underlying cache.
        Specified by:
        size in interface Map<K,​V>
        Returns:
        the number of key-value mappings in this map

      • values

        public Collection<V> values()
        Obtain an collection of the values contained in this map. If there is a listener for the back map, then the collection will be mutable; otherwise the returned collection will be immutable. The returned collection reflects the full contents of the back map.
        Specified by:
        values in interface Map<K,​V>
        Returns:
        a collection view of the values contained in this map

      • getInvalidationHits

        public long getInvalidationHits()
        Determine the rough number of front map invalidation hits since the cache statistics were last reset.

        An invalidation hit is an externally induced map event for an entry that exists in the front map.

        Returns:
        the number of cache invalidation hits

      • getInvalidationMisses

        public long getInvalidationMisses()
        Determine the rough number of front map invalidation misses since the cache statistics were last reset. An invalidation miss is an externally induced map event for an entry that does not exists in the front map.
        Returns:
        the number of cache invalidation misses

      • getTotalRegisterListener

        public long getTotalRegisterListener()
        Determine the total number of registerListener(Object oKey) operations since the cache statistics were last reset.
        Returns:
        the total number of listener registrations

      • toString

        public String toString()
        For debugging purposes, format the contents of the CachingMap in a human readable format.
        Overrides:
        toString in class Object
        Returns:
        a String representation of the CachingMap object

      • registerListener

        protected void registerListener()
        Register the global back map listener.

      • unregisterListener

        protected void unregisterListener()
        Unregister the global back map listener.

      • registerListener

        protected void registerListener​(Object oKey)
        Register the back map listener for the specified key.
        Parameters:
        oKey - the key

      • registerListeners

        protected void registerListeners​(Set setKeys)
        Register the back map listeners for the specified set of keys.
        Parameters:
        setKeys - the key set

      • unregisterListener

        protected void unregisterListener​(Object oKey)
        Unregister the back map listener for the specified key.
        Parameters:
        oKey - the key

      • unregisterListeners

        protected void unregisterListeners​(Set<K> setKeys)
        Unregister the back map listener for the specified keys.

        Note: all the keys in the passed-in set must be locked and will be unlocked.

        Parameters:
        setKeys - Set of keys to unregister (and unlock)

      • setKeyHolder

        protected Set setKeyHolder()
        Set up a thread local Set to hold all the keys that might be evicted from the front cache.
        Returns:
        a Set to hold all the keys in the ThreadLocal object or null if the bulk unregistering is not needed

      • removeKeyHolder

        protected void removeKeyHolder()
        Remove the key holder from the ThreadLocal object.

      • registerFrontListener

        protected void registerFrontListener()
        Register the global front map listener.

      • unregisterFrontListener

        protected void unregisterFrontListener()
        Unregister the global front map listener.

      • ensureInvalidationStrategy

        protected int ensureInvalidationStrategy()
        Ensure that a strategy has been chosen and that any appropriate global listeners have been registered.
        Returns:
        the current strategy

      • resetInvalidationStrategy

        protected void resetInvalidationStrategy()
        Reset the "current invalidation strategy" flag.

        This method should be called only while the access to the front map is fully synchronised and the front map is empty to prevent stalled data.

      • instantiateBackMapListener

        protected MapListener instantiateBackMapListener​(int nStrategy)
        Factory pattern: instantiate back map listener.
        Parameters:
        nStrategy - the strategy to instantiate a back map listener for
        Returns:
        an instance of back map listener responsible for keeping the front map coherent with the back map

      • registerDeactivationListener

        protected void registerDeactivationListener()
        Instantiate and register a DeactivationListener with the back cache.

      • unregisterDeactivationListener

        protected void unregisterDeactivationListener()
        Unregister back cache deactivation listener.

      • resetFrontMap

        public void resetFrontMap()
        Reset the front map.

      • unregisterMBean

        protected void unregisterMBean()
        Unregister an associated CacheMBean.

      • instantiateFrontMapListener

        protected CachingMap.FrontMapListener instantiateFrontMapListener()
        Factory pattern: instantiate front map listener.
        Returns:
        an instance of front map listener