CachingMap (Java API Reference for Oracle? Coherence Community Edition)

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 and 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 and Description
`static String[]`	`INVALIDATION_STRATEGY` String representation for `LISTEN_NONE`, `LISTEN_PRESENT`, `LISTEN_ALL`, `LISTEN_AUTO`, `LISTEN_LOGICAL`.
`static 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 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 int`	`LISTEN_LOGICAL` Invalidation strategy that instructs the CachingMap to listen to all back map events that are not synthetic deletes.
`static int`	`LISTEN_NONE` No invalidation strategy.
`static 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 and 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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`String`	`getInvalidationStrategy(int value)` Return string representation for invalidation strategy `value`.
`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.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 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
  - INVALIDATION_STRATEGY
```
public static final String[] INVALIDATION_STRATEGY
```
    String representation for LISTEN_NONE, LISTEN_PRESENT, LISTEN_ALL, LISTEN_AUTO, LISTEN_LOGICAL.
    
    Since:
    
    12.2.1.4.21
  - 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>
  - 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:
    
    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.
  - getInvalidationStrategy
```
public String getInvalidationStrategy(int value)
```
    Return string representation for invalidation strategy value.
    
    Parameters:
    
    value - one of LISTEN_*
    
    Returns:
    
    string for invalidation strategy
    
    Since:
    
    12.2.1.4.21
  - 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

Class CachingMap<K,V>

Nested Class Summary

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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Field Detail

LISTEN_NONE

LISTEN_PRESENT

LISTEN_ALL

LISTEN_AUTO

LISTEN_LOGICAL

INVALIDATION_STRATEGY

m_nStrategyTarget

m_nStrategyCurrent

m_listenerDeactivation

Constructor Detail

CachingMap

CachingMap

Method Detail

release

getFrontMap

getBackMap

getInvalidationStrategy

getControlMap

isCoherent

getCacheStatistics

clear

containsKey

containsValue

entrySet

get

getAll

getAllFromFrontMap

tryLock

isPriming

isCheckPrimingExclusively

isEmpty

keySet

put

put

putAll

invalidateFront

validate

remove

size

values

getInvalidationHits

getInvalidationMisses

getTotalRegisterListener

toString

registerListener

unregisterListener

registerListener

registerListeners

unregisterListener

unregisterListeners

setKeyHolder

removeKeyHolder

registerFrontListener

unregisterFrontListener

ensureInvalidationStrategy

resetInvalidationStrategy

instantiateBackMapListener

registerDeactivationListener

unregisterDeactivationListener

resetFrontMap

getInvalidationStrategy

unregisterMBean

instantiateFrontMapListener