com.tangosol.net.cache
Class CachingMap

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.net.cache.CachingMap

All Implemented Interfaces:

CacheStatistics, Map

Direct Known Subclasses:

NearCache

public class CachingMap
extends Base
implements Map, CacheStatistics

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.

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

protected class	CachingMap.BackMapListener MapListener for back map responsible for keeping the front map coherent with the back map.
protected class	CachingMap.FrontMapListener MapListener for front map responsible for deregistering back map listeners upon front map eviction.

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

Map.Entry

Field Summary

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

CachingMap(Map mapFront, Map mapBack)
Construct a CachingMap using two specified maps: FrontMap (aka "cache", "near" or "shallow") and BackMap (aka "actual", "real" or "deep").

CachingMap(Map mapFront, Map 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

void	clear() Clears both the front and back maps.
boolean	containsKey(Object oKey) Check whether or not this map contains a mapping for the specified key.
boolean	containsValue(Object oValue) Check whether or not this CachingMap maps one or more keys to the specified value.
protected int	ensureInvalidationStrategy() Ensure that a strategy has been choosen and that any appropriate global listeners have been registered.
Set	entrySet() Obtain an set view of the mappings contained in this map.
boolean	equals(Object o) Compares the specified object with this map for equality.
Object	get(Object oKey) Obtain the value to which this map maps the specified key.
Map	getAll(Collection colKeys) Get all the specified keys, if they are in the cache.
double	getAverageGetMillis() Determine the average number of milliseconds per get() invocation since the cache statistics were last reset.
double	getAverageHitMillis() Determine the average number of milliseconds per get() invocation that is a hit.
double	getAverageMissMillis() Determine the average number of milliseconds per get() invocation that is a miss.
double	getAveragePutMillis() Determine the average number of milliseconds per put() invocation since the cache statistics were last reset.
Map	getBackMap() Obtain the back map reference.
long	getCacheHits() Determine the rough number of cache hits since the cache statistics were last reset.
long	getCacheHitsMillis() Determine the total number of milliseconds (since that last statistics reset) for the get() operations for which an entry existed in this map.
long	getCacheMisses() Determine the rough number of cache misses since the cache statistics were last reset.
long	getCacheMissesMillis() Determine the total number of milliseconds (since that last statistics reset) for the get() operations for which no entry existed in this map.
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	getFrontMap() Obtain the front map reference.
double	getHitProbability() Determine the rough probability (0 <= p <= 1) that the next invocation will be a hit, based on the statistics collected since the last reset of the cache statistics.
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	getTotalGets() Determine the total number of get() operations since the cache statistics were last reset.
long	getTotalGetsMillis() Determine the total number of milliseconds spent on get() operations since the cache statistics were last reset.
long	getTotalPuts() Determine the total number of put() operations since the cache statistics were last reset.
long	getTotalPutsMillis() Determine the total number of milliseconds spent on put() operations since the cache statistics were last reset.
long	getTotalRegisterListener() Determine the total number of registerListener(Object oKey) operations since the cache statistics were last reset.
int	hashCode() Return the hash code value for this map.
protected MapListener	instantiateBackMapListener() 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	isCoherent() Determine if changes to the back map affect the front map so that data in the front map stays in sync.
boolean	isEmpty() Check whether or not this map is empty.
Set	keySet() Obtain an set view of the keys contained in this map.
Object	put(Object oKey, Object oValue) Associates the specified value with the specified key in this map.
Object	put(Object oKey, Object 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 map) Copy all of the mappings from the specified map to this map.
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.
void	release() Release the CachingMap.
Object	remove(Object oKey) Remove the mapping for this key from this map if present.
void	resetHitStatistics() Reset the cache statistics.
protected void	resetInvalidationStrategy() Reset the "current invalidation strategy" flag.
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 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	validate(MapEvent evt) Validate the front map entry for the specified back map event.
Collection	values() Obtain an collection of the values contained in this map.

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

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.

Constructor Detail

CachingMap

public CachingMap(Map mapFront,
                  Map 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 mapFront,
                  Map 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

Since:

Coherence 2.3

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

containsKey

public boolean containsKey(Object oKey)

Check whether or not this map contains a mapping for the specified key.

Specified by:

containsKey in interface Map

Returns:

true if this map contains a mapping for the specified key, false otherwise.

containsValue

public boolean containsValue(Object oValue)

Check whether or not this CachingMap maps one or more keys to the specified value.

Specified by:

containsValue in interface Map

Returns:

true if this CachingMap maps one or more keys to the specified value, false otherwise

entrySet

public Set entrySet()

Obtain an set view of the mappings contained in this map. If there is a listener for the back map, then the set will be mutable; otherwise the returned set will be immutable. The returned set reflects the full contents of the back map.

Specified by:

entrySet in interface Map

Returns:

a set view of the mappings contained in this map.

get

public Object get(Object oKey)

Obtain the value to which this map maps the specified key.

Specified by:

get in interface Map

Parameters:

oKey - the key object

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key

getAll

public Map getAll(Collection 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

isEmpty

public boolean isEmpty()

Check whether or not this map is empty. Expensive: always reflects the contents of the underlying cache.

Specified by:

isEmpty in interface Map

Returns:

true if this map contains no key-value mappings.

keySet

public Set keySet()

Obtain an set view of the keys contained in this map. If there is a listener for the back map, then the set will be mutable; otherwise the returned set will be immutable. The returned set reflects the full contents of the back map.

Specified by:

keySet in interface Map

Returns:

a set view of the keys contained in this map.

put

public Object put(Object oKey,
                  Object oValue)

Associates the specified value with the specified key in this map.

Specified by:

put in interface Map

Parameters:

oKey - key with which the specified value is to be associated

oValue - value to be associated with the specified key

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

put

public Object put(Object oKey,
                  Object 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 map)

Copy all of the mappings from the specified map to this map.

Specified by:

putAll in interface Map

Parameters:

map - Mappings to be stored in this map

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 Object remove(Object oKey)

Remove the mapping for this key from this map if present. Expensive: updates both the underlying cache and the local cache.

Specified by:

remove in interface Map

Parameters:

oKey - key whose mapping is to be removed from the map

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

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

Returns:

the number of key-value mappings in this map

values

public Collection 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

Returns:

a collection view of the values contained in this map

getTotalGets

public long getTotalGets()

Determine the total number of get() operations since the cache statistics were last reset.

Specified by:

getTotalGets in interface CacheStatistics

Returns:

the total number of get() operations

getTotalGetsMillis

public long getTotalGetsMillis()

Determine the total number of milliseconds spent on get() operations since the cache statistics were last reset.

Specified by:

getTotalGetsMillis in interface CacheStatistics

Returns:

the total number of milliseconds processing get() operations

getAverageGetMillis

public double getAverageGetMillis()

Determine the average number of milliseconds per get() invocation since the cache statistics were last reset.

Specified by:

getAverageGetMillis in interface CacheStatistics

Returns:

the average number of milliseconds per get() operation

getTotalPuts

public long getTotalPuts()

Determine the total number of put() operations since the cache statistics were last reset.

Specified by:

getTotalPuts in interface CacheStatistics

Returns:

the total number of put() operations

getTotalPutsMillis

public long getTotalPutsMillis()

Determine the total number of milliseconds spent on put() operations since the cache statistics were last reset.

Specified by:

getTotalPutsMillis in interface CacheStatistics

Returns:

the total number of milliseconds processing put() operations

getAveragePutMillis

public double getAveragePutMillis()

Determine the average number of milliseconds per put() invocation since the cache statistics were last reset.

Specified by:

getAveragePutMillis in interface CacheStatistics

Returns:

the average number of milliseconds per put() operation

getCacheHits

public long getCacheHits()

Determine the rough number of cache hits since the cache statistics were last reset.

A cache hit is a read operation invocation (i.e. get()) for which an entry exists in this map.

Specified by:

getCacheHits in interface CacheStatistics

Returns:

the number of get(java.lang.Object) calls that have been served by existing cache entries

getCacheHitsMillis

public long getCacheHitsMillis()

Determine the total number of milliseconds (since that last statistics reset) for the get() operations for which an entry existed in this map.

Specified by:

getCacheHitsMillis in interface CacheStatistics

Returns:

the total number of milliseconds for the get() operations that were hits

getAverageHitMillis

public double getAverageHitMillis()

Determine the average number of milliseconds per get() invocation that is a hit.

Specified by:

getAverageHitMillis in interface CacheStatistics

Returns:

the average number of milliseconds per cache hit

getCacheMisses

public long getCacheMisses()

Determine the rough number of cache misses since the cache statistics were last reset.

A cache miss is a get() invocation that does not have an entry in this map.

Specified by:

getCacheMisses in interface CacheStatistics

Returns:

the number of get(Object) calls that failed to find an existing cache entry because the requested key was not in the cache

getCacheMissesMillis

public long getCacheMissesMillis()

Determine the total number of milliseconds (since that last statistics reset) for the get() operations for which no entry existed in this map.

Specified by:

getCacheMissesMillis in interface CacheStatistics

Returns:

the total number of milliseconds (since that last statistics reset) for the get() operations that were misses

getAverageMissMillis

public double getAverageMissMillis()

Determine the average number of milliseconds per get() invocation that is a miss.

Specified by:

getAverageMissMillis in interface CacheStatistics

Returns:

the average number of milliseconds per cache miss

getHitProbability

public double getHitProbability()

Determine the rough probability (0 <= p <= 1) that the next invocation will be a hit, based on the statistics collected since the last reset of the cache statistics.

Specified by:

getHitProbability in interface CacheStatistics

Returns:

the cache hit probability (0 <= p <= 1)

resetHitStatistics

public void resetHitStatistics()

Reset the cache statistics.

Specified by:

resetHitStatistics in interface CacheStatistics

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

equals

public boolean equals(Object o)

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings.

Specified by:

equals in interface Map

Parameters:

o - object to be compared for equality with this map

Returns:

true if the specified object is equal to this map

hashCode

public int hashCode()

Return the hash code value for this map.

Specified by:

hashCode in interface Map

Returns:

the hash code value for this map

toString

public String toString()

For debugging purposes, format the contents of the CachingMap in a human readable format.

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

unregisterListener

protected void unregisterListener(Object oKey)

Unregister the back map listener for the specified key.

Parameters:

oKey - the key

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 choosen 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 synchronzied and the front map is empty to prevent stalled data.

instantiateBackMapListener

protected MapListener instantiateBackMapListener()

Factory pattern: instantiate back map listener.

Returns:

an instance of back map listener responsible for keeping the front map coherent with the back map

instantiateFrontMapListener

protected CachingMap.FrontMapListener instantiateFrontMapListener()

Factory pattern: instantiate front map listener.

Returns:

an instance of front map listener