Package com.tangosol.net.cache

Class CachingMap<K,V>

java.lang.Object
com.tangosol.net.cache.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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected class 
    CachingMap.DeactivationListener
    DeactivationListener for the back NamedCache.
    protected class 
    CachingMap.FrontMapListener
    MapListener for front map responsible for deregistering back map listeners upon front map eviction.
    protected class 
    CachingMap.PrimingListener
    MapListener for back map responsible for keeping the front map coherent with the back map.
    protected class 
    CachingMap.SimpleListener
    MapListener for back map responsible for keeping the front map coherent with the back map.

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

    Map.Entry<K,V>

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    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.
    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.
    static final int
    LISTEN_LOGICAL
    Invalidation strategy that instructs the CachingMap to listen to all back map events that are not synthetic deletes.
    static final int
    LISTEN_NONE
    No invalidation strategy.
    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.
    protected com.tangosol.internal.net.NamedCacheDeactivationListener
    m_listenerDeactivation
    The NamedCache deactivation listener.
    protected int
    m_nStrategyCurrent
    The current invalidation strategy, which at times could be different from the target strategy.
    protected int
    m_nStrategyTarget
    The invalidation strategy that this map is to use.

  • Constructor Summary

    Constructors
    Constructor
    Description
    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").
    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.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Clears both the front and back maps.
    boolean
    containsKey(Object oKey)
    boolean
    containsValue(Object oValue)
    protected int
    ensureInvalidationStrategy()
    Ensure that a strategy has been chosen and that any appropriate global listeners have been registered.
    Set<Map.Entry<K,V>>
    entrySet()
    V
    get(Object oKey)
    Map<K,V>
    getAll(Collection<? extends K> colKeys)
    Get all the specified keys, if they are in the cache.
    protected Map<K,V>
    getAllFromFrontMap(Collection<? extends K> colKeys)
    Retrieve entries from the front map.
    Map<K,V>
    getBackMap()
    Obtain the back map reference.
    CacheStatistics
    getCacheStatistics()
    Obtain the CacheStatistics for this cache.
    ConcurrentMap
    getControlMap()
    Obtain the ConcurrentMap that should be used to synchronize the front map modification access.
    Map<K,V>
    getFrontMap()
    Obtain the front map reference.
    long
    getInvalidationHits()
    Determine the rough number of front map invalidation hits since the cache statistics were last reset.
    long
    getInvalidationMisses()
    Determine the rough number of front map invalidation misses since the cache statistics were last reset.
    int
    getInvalidationStrategy()
    Obtain the invalidation strategy used by this CachingMap.
    long
    getTotalRegisterListener()
    Determine the total number of registerListener(Object oKey) operations since the cache statistics were last reset.
    protected MapListener
    instantiateBackMapListener(int nStrategy)
    Factory pattern: instantiate back map listener.
    protected CachingMap<K,V>.FrontMapListener
    instantiateFrontMapListener()
    Factory pattern: instantiate front map listener.
    protected void
    invalidateFront(Object oKey)
    Invalidate the key from the front.
    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).
    protected boolean
    isCoherent()
    Determine if changes to the back map affect the front map so that data in the front map stays in sync.
    boolean
    isEmpty()
    protected boolean
    isPriming(MapEvent evt)
    Check if the specified event is a "priming" one.
    Set<K>
    keySet()
    V
    put(K oKey, V oValue)
    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.
    void
    putAll(Map<? extends K,? extends V> map)
    protected void
    registerDeactivationListener()
    Instantiate and register a DeactivationListener with the back cache.
    protected void
    registerFrontListener()
    Register the global front map listener.
    protected void
    registerListener()
    Register the global back map listener.
    protected void
    registerListener(Object oKey)
    Register the back map listener for the specified key.
    protected void
    registerListeners(Set setKeys)
    Register the back map listeners for the specified set of keys.
    void
    release()
    Release the CachingMap.
    V
    remove(Object oKey)
    protected void
    removeKeyHolder()
    Remove the key holder from the ThreadLocal object.
    void
    resetFrontMap()
    Reset the front map.
    protected void
    resetInvalidationStrategy()
    Reset the "current invalidation strategy" flag.
    protected Set
    setKeyHolder()
    Set up a thread local Set to hold all the keys that might be evicted from the front cache.
    int
    size()
    Return the number of key-value mappings in this map.
    String
    toString()
    For debugging purposes, format the contents of the CachingMap in a human readable format.
    protected Set<K>
    tryLock(Set<K> setKeys)
    Lock the keys in the given set without blocking.
    protected void
    unregisterDeactivationListener()
    Unregister back cache deactivation listener.
    protected void
    unregisterFrontListener()
    Unregister the global front map listener.
    protected void
    unregisterListener()
    Unregister the global back map listener.
    protected void
    unregisterListener(Object oKey)
    Unregister the back map listener for the specified key.
    protected void
    unregisterListeners(Set<K> setKeys)
    Unregister the back map listener for the specified keys.
    protected void
    unregisterMBean()
    Unregister an associated CacheMBean.
    protected void
    validate(MapEvent evt)
    Validate the front map entry for the specified back map event.
    Collection<V>
    values()
    Obtain an collection of the values contained in this map.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Map

    compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

  • Field Details

    • LISTEN_NONE

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

    • 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:

    • 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:

    • 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:

    • 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:

    • 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 Details

    • 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:
      mapFront - front map
      mapBack - back map
      See Also:

    • 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 Details

    • 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>

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Specified by:
      entrySet 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:

    • 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<K,V>.FrontMapListener instantiateFrontMapListener()
      Factory pattern: instantiate front map listener.
      Returns:
      an instance of front map listener