Skip navigation links

com.tangosol.net.cache
Class CompactSerializationCache

java.lang.Object
com.tangosol.util.Base
com.tangosol.util.AbstractKeyBasedMap
com.tangosol.net.cache.CompactSerializationCache

All Implemented Interfaces:

com.oracle.common.base.Disposable, CacheMap, ConfigurableCacheMap, ObservableMap, java.util.Map

Direct Known Subclasses:

BlindCompactSerializationCache

public class CompactSerializationCache

extends AbstractKeyBasedMap

implements ConfigurableCacheMap, com.oracle.common.base.Disposable

CompactSerializationCache is an implementation of ConfigurableCacheMap which is optimized for compact on-heap footprint.

This implementation is partially thread-safe. It assumes that multiple threads will not be accessing the same keys at the same time, nor would any other thread be accessing this cache while a clear() operation were going on, for example. In other words, this implementation assumes that access to this cache is either single-threaded or gated through an object like WrapperConcurrentMap.

Since:

Coherence 12.1.2

Author:

rhl 2013.01.23

Nested Class Summary

protected class	CompactSerializationCache.DeferredCacheEvent A DeferredCacheEvent is a CacheEvent object that defers the loading of the old value.
protected class	CompactSerializationCache.HybridEvictionPolicy The EvictionPolicy object for the Hybrid eviction algorithm.
protected class	CompactSerializationCache.InternalEvictionPolicy InternalEvictionPolicy is an abstract base implementation of an ConfigurableCacheMap.EvictionPolicy used by this CompactSerializationCache.
protected class	CompactSerializationCache.KeySet A KeySet implementation optimized for CompactSerializationCache.
protected class	CompactSerializationCache.LFUEvictionPolicy An EvictionPolicy implementing the Least Frequently Used (LFU) algorithm.
protected class	CompactSerializationCache.LRUEvictionPolicy An EvictionPolicy implementing the Least Recently Used (LRU) algorithm.
protected static class	CompactSerializationCache.TouchCountVisitor TouchCountVisitor is applied to the touch-count map by EvictionPolicy implementations that rely on the touch-count to retrieve and adjust the touch-count.
protected class	CompactSerializationCache.WrapperEvictionPolicy WrapperEvictionPolicy is used to wrap external or "custom" EvictionPolicy implementations to adapt the internal Binary key-based API to the Entry-based API.

Nested classes/interfaces inherited from class com.tangosol.util.AbstractKeyBasedMap

AbstractKeyBasedMap.EntrySet, AbstractKeyBasedMap.ValuesCollection

Nested classes/interfaces inherited from interface com.tangosol.net.cache.ConfigurableCacheMap

ConfigurableCacheMap.Entry, ConfigurableCacheMap.EvictionApprover, ConfigurableCacheMap.EvictionPolicy, ConfigurableCacheMap.UnitCalculator

Field Summary

static double	DEFAULT_PRUNE By default, when the cache prunes, it reduces its entries to this percentage.
protected java.util.concurrent.atomic.AtomicLong	f_atomicCurUnits Current number of units to in the cache.
protected java.util.concurrent.atomic.AtomicBoolean	f_atomicEvictingMutex The mutex acquired by the thread performing the cache eviction.
protected java.util.concurrent.atomic.AtomicBoolean	f_atomicExpiringMutex The mutex acquired by the thread performing the cache-wide expiration.
protected boolean	f_fBinary True iff the keys and values are known to be Binary (and not require conversion).
protected long	f_ldtEpoch The time of the start of the "epoch", relative to which internal time-offsets are stored.
protected java.lang.ClassLoader	f_loader The ClassLoader to use for deserialization of non-Binary keys/values.
protected MultiBinaryLongMap	f_mblm The MultiBinaryLongMap used for compact key (and entry-attribute) storage.
protected SimpleCacheStatistics	f_stats The CacheStatistics for JMX.
protected BinaryStore.KeySetAware	f_store The BinaryStore.KeySetAware that this CompactSerializationCache uses to store data.
protected BinaryLongMap.EntryVisitor	f_visitorDefaultExpiry The singleton stateless EntryVisitor used to update the ExpiryMap with the default expiry.
protected ConfigurableCacheMap.EvictionApprover	m_apprvrEvict The EvictionApprover.
protected BinaryLongMap	m_blmExpiry The BinaryLongMap holding the expiry information for the entries in the Cache Map.
protected BinaryLongMap	m_blmTouchCount The BinaryLongMap holding the touch-count information for the entries in the Cache Map.
protected BinaryLongMap	m_blmTouchTime The BinaryLongMap holding the touch-time information for the entries in the Cache Map.
protected BinaryLongMap	m_blmUnits The BinaryLongMap holding the units for each entry in the Cache Map.
protected ConfigurableCacheMap.UnitCalculator	m_calculator The unit calculator to use to limit size of the cache.
protected int	m_cExpiryDelay The default expiry int milliseconds, or 0 for no timeout.
protected long	m_cMaxUnits Maximum number of units to manage in the cache.
protected long	m_cPruneUnits The number of units to prune the cache down to.
protected double	m_dflPruneLevel The percentage of the total number of units that will remain after the cache manager prunes the cache (i.e. this is the "low water mark" value); this value is in the range 0.0 to 1.0.
protected boolean	m_fBlind True iff this Map should operate in blind mode.
protected long	m_ldtNextExpiryCheck The time that the last cache-wide expiry check was performed.
protected MapListenerSupport	m_listenerSupport The MapListenerSupport object.
protected int	m_nUnitFactor The unit factor.
protected CompactSerializationCache.InternalEvictionPolicy	m_policy The EvictionPolicy.

Fields inherited from interface com.tangosol.net.cache.CacheMap

EXPIRY_DEFAULT, EXPIRY_NEVER

Constructor Summary

	CompactSerializationCache(BinaryStoreManager mgr, boolean fBinary) Construct a CompactSerializationCache using the specified BinaryStoreManager, optionally storing only Binary keys and values
	CompactSerializationCache(BinaryStoreManager mgr, java.lang.ClassLoader loader) Construct a CompactSerializationCache using the specified BinaryStoreManager and classloader.
protected	CompactSerializationCache(BinaryStoreManager mgr, java.lang.ClassLoader loader, boolean fBinary) Construct a CompactSerializationCache using the specified BinaryStoreManager.

Method Summary

void	addMapListener(MapListener listener) Add a standard map listener that will receive all events (inserts, updates, deletes) that occur against the map, with the key, old-value and new-value included.
void	addMapListener(MapListener listener, Filter filter, boolean fLite) Add a map listener that receives events based on a filter evaluation.
void	addMapListener(MapListener listener, java.lang.Object oKey, boolean fLite) Add a map listener for a specific key.
protected int	calculateUnits(Binary binKey, Binary binValue) Calculate the unit cost of the specified cache entry, according to the configured unit-calculator.
protected void	checkExpiry(Binary binKey) Check the specified key to see if it is expired, removing it if necessary.
protected void	checkExpiry(boolean fForce) Check the cache entries for expiration, removing expired entries as necessary.
protected void	checkSize() Check the current size of the cache to see that it is within the configured high-units, evicting entries according to the configured ConfigurableCacheMap.EvictionPolicy if necessary.
protected void	checkSize(boolean fCheckExpiry) Check the current size of the cache to see that it is within the configured high-units, evicting entries according to the configured ConfigurableCacheMap.EvictionPolicy if necessary.
void	clear() Clear all key/value mappings.
protected void	configureEviction() Ensure that the BinaryLongMaps required for eviction support are configured.
boolean	containsKey(java.lang.Object oKey) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object oValue) Returns true if this Map maps one or more keys to the specified value.
protected long	decodeExpiry(long cExpiryEncoded) Decode the specified encoded expiry value into an absolute time.
protected long	decodeTime(int cEncoded) Decode the specified encoded time into an absolute ldt.
protected void	dispatchEvent(int nId, Binary binKey, java.lang.Object oKey, java.lang.Object oValueOld, java.lang.Object oValueNew, boolean fSynthetic) Dispatch the passed event.
void	dispose()
protected long	encodeExpiry(long cExpiryDelay) Encode the specified expiry delay (relative to current time) into the internal format.
protected int	encodeTime(long ldt) Encode the specified time into an opaque 32-bit value.
protected BinaryLongMap	ensureExpiryMap() Ensure that the expiry-map is initialized.
void	evict() Evict all entries from the cache that are no longer valid, and potentially prune the cache size if the cache is size-limited and its size is above the caching low water mark.
void	evict(java.lang.Object oKey) Evict a specified key from the cache, as if it had expired from the cache.
void	evictAll(java.util.Collection colKeys) Evict the specified keys from the cache, as if they had each expired from the cache.
protected int	evictInternal(Binary binKey) Attempt to evict the cache entry for the specified key from the cache as a result of either expiration or size-triggered eviction, returning the unit-size of the evicted entry, or 0 if the eviction was disallowed by the ConfigurableCacheMap.EvictionApprover.
protected java.lang.Object	fromBinary(Binary bin) Translate the passed Binary object into an Object object.
java.lang.Object	get(java.lang.Object oKey) Returns the value to which this map maps the specified key.
BinaryStore.KeySetAware	getBinaryStore() Returns the BinaryStore that this map uses for its storage.
ConfigurableCacheMap.Entry	getCacheEntry(java.lang.Object oKey) Locate a cache Entry in the cache based on its key.
protected ConfigurableCacheMap.Entry	getCacheEntryInternal(Binary binKey) Return a ConfigurableCacheMap.Entry for the specified key.
protected ConfigurableCacheMap.Entry	getCacheEntryInternal(Binary binKey, java.lang.Object oKey) Return a ConfigurableCacheMap.Entry for the specified key.
CacheStatistics	getCacheStatistics() Returns the CacheStatistics for this cache.
java.lang.ClassLoader	getClassLoader() Return the configured ClassLoader, or null if none is configured.
protected int	getEntryUnits(Binary binKey) Return the unit-size of the entry associated with the specified key, or 0 if the key does not exist.
ConfigurableCacheMap.EvictionApprover	getEvictionApprover() Obtain the registered EvictionApprover.
ConfigurableCacheMap.EvictionPolicy	getEvictionPolicy() Obtain the current EvictionPolicy used by the cache.
int	getExpiryDelay() Determine the default "time to live" for each individual cache entry.
BinaryLongMap	getExpiryMap() Return the BinaryLongMap associating the entries in this cache map with their corresponding expiry.
int	getHighUnits() Determine the limit of the cache size in units.
protected CompactSerializationCache.InternalEvictionPolicy	getInternalEvictionPolicy() Return the InternalEvictionPolicy used by this CompactSerializationCache.
protected BinaryLongMap	getKeyMap() Return a BinaryLongMap whose values have no meaning, but whose keys can be used internally to detect the presence of an entry in the cache map.
int	getLowUnits() Determine the point to which the cache will shrink when it prunes.
BinaryLongMap	getTouchCountMap() Return the BinaryLongMap associating the entries in this cache map with their corresponding touch count.
BinaryLongMap	getTouchTimeMap() Return the BinaryLongMap associating the entries in this cache map with their corresponding last "touch" time.
ConfigurableCacheMap.UnitCalculator	getUnitCalculator() Obtain the current UnitCalculator used by the cache.
int	getUnitFactor() Determine the factor by which the Units, LowUnits and HighUnits properties are adjusted.
int	getUnits() Determine the number of units that the cache currently stores.
BinaryLongMap	getUnitsMap() Return the BinaryLongMap associating the entries in this cache map with their size in "units".
protected boolean	hasListeners() Determine if the cache map has any listeners at all.
protected CompactSerializationCache.DeferredCacheEvent	instantiateDeferredCacheEvent(int nId, Binary binKey, java.lang.Object oKey, java.lang.Object oValueOld, java.lang.Object oValueNew, boolean fSynthetic) Create a DeferredCacheEvent object with the provided arguments.
protected java.util.Set	instantiateKeySet() Factory pattern: Create a Set that represents the keys in the Map
boolean	isBinaryMap() Determine if the keys and values in this map are known to be all Binary.
boolean	isBlind() Return whether this CompactSerializationCache instance is in blind mode.
protected java.util.Iterator	iterateKeys() Create an iterator over the keys in this Map.
java.lang.Object	put(java.lang.Object oKey, java.lang.Object oValue) Associates the specified value with the specified key in this map.
java.lang.Object	put(java.lang.Object oKey, java.lang.Object oValue, long cExpiry) Associates the specified value with the specified key in this cache.
protected void	registerExpiry(Binary binKey, long cExpiry) Register the expiry for the specified key.
java.lang.Object	remove(java.lang.Object oKey) Removes the mapping for this key from this map if present.
protected boolean	removeBlind(java.lang.Object oKey) Removes the mapping for this key from this map if present.
protected java.lang.Object	removeInternal(java.lang.Object oKey, Binary binKey, boolean fBlind) Remove the given key from the BinaryStore only loading the value if necessary.
void	removeMapListener(MapListener listener) Remove a standard map listener that previously signed up for all events.
void	removeMapListener(MapListener listener, Filter filter) Remove a map listener that previously signed up for events based on a filter evaluation.
void	removeMapListener(MapListener listener, java.lang.Object oKey) Remove a map listener that previously signed up for events about a specific key.
void	setBlind(boolean fBlind) Set whether this CompactSerializationCache instance should operate under a blind mode.
void	setEvictionApprover(ConfigurableCacheMap.EvictionApprover approver) Set the EvictionApprover for this ConfigurableCacheMap.
void	setEvictionPolicy(ConfigurableCacheMap.EvictionPolicy policy) Set the EvictionPolicy for the cache to use.
void	setExpiryDelay(int cMillis) Specify the default "time to live" for cache entries.
protected void	setExpiryMap(BinaryLongMap blmExpiry) Set the BinaryLongMap to use to associate the entries in this cache map with their corresponding expiry.
void	setHighUnits(int cMax) Update the maximum size of the cache in units.
void	setLowUnits(int cUnits) Specify the point to which the cache will shrink when it prunes.
protected void	setTouchCountMap(BinaryLongMap blmTouch) Return the BinaryLongMap to use to associate the entries in this cache map with their corresponding "touch" count.
protected void	setTouchTimeMap(BinaryLongMap blmTouch) Return the BinaryLongMap to use to associate the entries in this cache map with their corresponding last "touch" time.
void	setUnitCalculator(ConfigurableCacheMap.UnitCalculator calculator) Set the UnitCalculator for the cache to use.
void	setUnitFactor(int nFactor) Determine the factor by which the Units, LowUnits and HighUnits properties are adjusted.
protected void	setUnitsMap(BinaryLongMap blmUnits) Set the BinaryLongMap to use to associate the entries in this cache map with their size in "units".
int	size() Returns the number of key-value mappings in this map.
protected Binary	toBinary(java.lang.Object o) Translate the passed Object object into an Binary object.
protected static int	toExternalUnits(long cUnits, int nFactor) Convert from an internal 64-bit unit value to an external 32-bit unit value using the configured units factor.
protected static long	toInternalUnits(int cUnits, int nFactor) Convert from an external 32-bit unit value to an internal 64-bit unit value using the configured units factor.
java.lang.String	toString() Returns a string representation of this Map.
protected void	touch(Binary binKey) Register a "touch" of the specified key.
protected void	updateUnits(Binary binKey, int cUnits) Update the units associated with the specified key.

Methods inherited from class com.tangosol.util.AbstractKeyBasedMap

clone, entrySet, equals, getAll, hashCode, instantiateEntrySet, instantiateValues, isEmpty, keySet, putAll, values

Methods inherited from interface com.tangosol.net.cache.CacheMap

getAll

Methods inherited from interface java.util.Map

entrySet, equals, hashCode, isEmpty, keySet, putAll, values

Field Detail

DEFAULT_PRUNE

public static final double DEFAULT_PRUNE

By default, when the cache prunes, it reduces its entries to this percentage.

See Also:

Constant Field Values

m_blmExpiry

protected BinaryLongMap m_blmExpiry

The BinaryLongMap holding the expiry information for the entries in the Cache Map.

m_blmTouchTime

protected BinaryLongMap m_blmTouchTime

The BinaryLongMap holding the touch-time information for the entries in the Cache Map.

m_blmTouchCount

protected BinaryLongMap m_blmTouchCount

The BinaryLongMap holding the touch-count information for the entries in the Cache Map.

m_blmUnits

protected BinaryLongMap m_blmUnits

The BinaryLongMap holding the units for each entry in the Cache Map.

f_store

protected final BinaryStore.KeySetAware f_store

The BinaryStore.KeySetAware that this CompactSerializationCache uses to store data.

m_cMaxUnits

protected long m_cMaxUnits

Maximum number of units to manage in the cache.

m_dflPruneLevel

protected double m_dflPruneLevel

The percentage of the total number of units that will remain after the cache manager prunes the cache (i.e. this is the "low water mark" value); this value is in the range 0.0 to 1.0.

m_cPruneUnits

protected long m_cPruneUnits

The number of units to prune the cache down to.

f_atomicCurUnits

protected final java.util.concurrent.atomic.AtomicLong f_atomicCurUnits

Current number of units to in the cache.

m_calculator

protected ConfigurableCacheMap.UnitCalculator m_calculator

The unit calculator to use to limit size of the cache.

m_nUnitFactor

protected int m_nUnitFactor

The unit factor.

m_cExpiryDelay

protected int m_cExpiryDelay

The default expiry int milliseconds, or 0 for no timeout.

m_ldtNextExpiryCheck

protected long m_ldtNextExpiryCheck

The time that the last cache-wide expiry check was performed.

m_policy

protected CompactSerializationCache.InternalEvictionPolicy m_policy

The EvictionPolicy.

m_apprvrEvict

protected ConfigurableCacheMap.EvictionApprover m_apprvrEvict

The EvictionApprover.

m_listenerSupport

protected MapListenerSupport m_listenerSupport

The MapListenerSupport object.

m_fBlind

protected boolean m_fBlind

True iff this Map should operate in blind mode. Blind mode allows a Map implementation to forgo the often costly parts of the Map API, in particular returning the previous value for both remove and put operations. Additionally, for CCMs that dispatch events fetching the previous value can also be avoided.

f_mblm

protected final MultiBinaryLongMap f_mblm

The MultiBinaryLongMap used for compact key (and entry-attribute) storage.

f_atomicExpiringMutex

protected final java.util.concurrent.atomic.AtomicBoolean f_atomicExpiringMutex

The mutex acquired by the thread performing the cache-wide expiration.

f_atomicEvictingMutex

protected final java.util.concurrent.atomic.AtomicBoolean f_atomicEvictingMutex

The mutex acquired by the thread performing the cache eviction.

f_fBinary

protected final boolean f_fBinary

True iff the keys and values are known to be Binary (and not require conversion).

f_loader

protected final java.lang.ClassLoader f_loader

The ClassLoader to use for deserialization of non-Binary keys/values.

f_ldtEpoch

protected final long f_ldtEpoch

The time of the start of the "epoch", relative to which internal time-offsets are stored.

f_visitorDefaultExpiry

protected final BinaryLongMap.EntryVisitor f_visitorDefaultExpiry

The singleton stateless EntryVisitor used to update the ExpiryMap with the default expiry. See registerExpiry(com.tangosol.util.Binary, long).

f_stats

protected final SimpleCacheStatistics f_stats

The CacheStatistics for JMX.

Constructor Detail

CompactSerializationCache

public CompactSerializationCache(BinaryStoreManager mgr,
                                 java.lang.ClassLoader loader)

Construct a CompactSerializationCache using the specified BinaryStoreManager and classloader.

Parameters:

mgr - the BinaryStoreManager to use to create the BinaryStore

loader - the ClassLoader to use for deserialization

CompactSerializationCache

public CompactSerializationCache(BinaryStoreManager mgr,
                                 boolean fBinary)

Construct a CompactSerializationCache using the specified BinaryStoreManager, optionally storing only Binary keys and values

Parameters:

mgr - the BinaryStoreManager to use to create the BinaryStore

fBinary - true iff only Binary keys and values are to be stored

CompactSerializationCache

protected CompactSerializationCache(BinaryStoreManager mgr,
                                    java.lang.ClassLoader loader,
                                    boolean fBinary)

Construct a CompactSerializationCache using the specified BinaryStoreManager.

Parameters:

mgr - the BinaryStoreManager to use to create the BinaryStore

loader - the ClassLoader to use for deserialization

fBinary - true iff only Binary keys and values are to be stored

Method Detail

getBinaryStore

public BinaryStore.KeySetAware getBinaryStore()

Returns the BinaryStore that this map uses for its storage.

Returns:

the BinaryStore

getClassLoader

public java.lang.ClassLoader getClassLoader()

Return the configured ClassLoader, or null if none is configured.

Returns:

the classloader to use for deserialization, or null

isBinaryMap

public boolean isBinaryMap()

Determine if the keys and values in this map are known to be all Binary.

Returns:

true if all keys and values will be Binary to start with, and thus will not require conversion

getExpiryMap

public BinaryLongMap getExpiryMap()

Return the BinaryLongMap associating the entries in this cache map with their corresponding expiry.

Note: it is legal for an expiry to be 0 (meaning no-expiry), but the contract of the BinaryLongMap considers 0 to be missing, so operations such as size() and keys() on the returned BLM will not reflect the entire set of keys in this cache

Returns:

the BinaryLongMap holding the expiry information

setExpiryMap

protected void setExpiryMap(BinaryLongMap blmExpiry)

Set the BinaryLongMap to use to associate the entries in this cache map with their corresponding expiry.

Parameters:

blmExpiry - the BinaryLongMap to use to hold the expiry information

getKeyMap

protected BinaryLongMap getKeyMap()

Return a BinaryLongMap whose values have no meaning, but whose keys can be used internally to detect the presence of an entry in the cache map.

Note: the returned BinaryLongMap may not be mutated.

Returns:

a BinaryLongMap containing all keys in this CacheMap, mapped to an unspecified value

getTouchTimeMap

public BinaryLongMap getTouchTimeMap()

Return the BinaryLongMap associating the entries in this cache map with their corresponding last "touch" time. A "touch" is any access (read or write) to an entry.

Returns:

the BinaryLongMap holding the touch-time information

setTouchTimeMap

protected void setTouchTimeMap(BinaryLongMap blmTouch)

Return the BinaryLongMap to use to associate the entries in this cache map with their corresponding last "touch" time. A "touch" is any access (read or write) to an entry.

Parameters:

blmTouch - the BinaryLongMap holding the touch-time information

getTouchCountMap

public BinaryLongMap getTouchCountMap()

Return the BinaryLongMap associating the entries in this cache map with their corresponding touch count. A "touch" is any access (read or write) to an entry.

Returns:

the BinaryLongMap holding the touch count information

setTouchCountMap

protected void setTouchCountMap(BinaryLongMap blmTouch)

Return the BinaryLongMap to use to associate the entries in this cache map with their corresponding "touch" count. A "touch" is any access (read or write) to an entry.

Parameters:

blmTouch - the BinaryLongMap holding the touch count information

getUnitsMap

public BinaryLongMap getUnitsMap()

Return the BinaryLongMap associating the entries in this cache map with their size in "units".

Returns:

the BinaryLongMap holding the units

setUnitsMap

protected void setUnitsMap(BinaryLongMap blmUnits)

Set the BinaryLongMap to use to associate the entries in this cache map with their size in "units".

Parameters:

blmUnits - the BinaryLongMap to use for storing the units

hasListeners

protected boolean hasListeners()

Determine if the cache map has any listeners at all.

Returns:

true iff this cache map has at least one MapListener

getCacheStatistics

public CacheStatistics getCacheStatistics()

Returns the CacheStatistics for this cache.

Note: this method is invoked reflectively by the CacheModel

Returns:

a CacheStatistics object

isBlind

public boolean isBlind()

Return whether this CompactSerializationCache instance is in blind mode. Blind mode allows this Map implementation to forgo the often costly parts of the Map API, in particular returning the previous value for both remove and put operations.

Returns:

whether this CompactSerializationCache is operating in a blind mode

setBlind

public void setBlind(boolean fBlind)

Set whether this CompactSerializationCache instance should operate under a blind mode.

Parameters:

fBlind - whether this CompactSerializationCache should operate under a blind mode

size

public int size()

Returns the number of key-value mappings in this map.

Specified by:

size in interface java.util.Map

Overrides:

size in class AbstractKeyBasedMap

Returns:

the number of key-value mappings in this map

containsKey

public boolean containsKey(java.lang.Object oKey)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map

Overrides:

containsKey in class AbstractKeyBasedMap

Returns:

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

containsValue

public boolean containsValue(java.lang.Object oValue)

Returns true if this Map maps one or more keys to the specified value.

Specified by:

containsValue in interface java.util.Map

Overrides:

containsValue in class AbstractKeyBasedMap

Returns:

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

get

public java.lang.Object get(java.lang.Object oKey)

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

Specified by:

get in interface java.util.Map

Specified by:

get in class AbstractKeyBasedMap

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

remove

public java.lang.Object remove(java.lang.Object oKey)

Removes 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 java.util.Map

Overrides:

remove in class AbstractKeyBasedMap

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.

clear

public void clear()

Clear all key/value mappings.

Specified by:

clear in interface java.util.Map

Overrides:

clear in class AbstractKeyBasedMap

put

public java.lang.Object put(java.lang.Object oKey,
                            java.lang.Object oValue)

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

Specified by:

put in interface CacheMap

Specified by:

put in interface java.util.Map

Overrides:

put in class AbstractKeyBasedMap

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

put

public java.lang.Object put(java.lang.Object oKey,
                            java.lang.Object oValue,
                            long cExpiry)

Associates the specified value with the specified key in this cache. If the cache previously contained a mapping for this key, the old value is replaced. This variation of the CacheMap.put(Object oKey, Object oValue) method allows the caller to specify an expiry (or "time to live") for the cache entry.

Specified by:

put in interface CacheMap

Parameters:

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

oValue - value to be associated with the specified key

cExpiry - the number of milliseconds until the cache entry will expire, also referred to as the entry's "time to live"; pass CacheMap.EXPIRY_DEFAULT to use the cache's default time-to-live setting; pass CacheMap.EXPIRY_NEVER to indicate that the cache entry should never expire; this milliseconds value is not a date/time value, such as is returned from System.currentTimeMillis()

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

instantiateKeySet

protected java.util.Set instantiateKeySet()

Factory pattern: Create a Set that represents the keys in the Map

Overrides:

instantiateKeySet in class AbstractKeyBasedMap

Returns:

a new instance of Set that represents the keys in the Map

iterateKeys

protected java.util.Iterator iterateKeys()

Create an iterator over the keys in this Map. The Iterator must support remove() if the Map supports removal.

Specified by:

iterateKeys in class AbstractKeyBasedMap

Returns:

a new instance of an Iterator over the keys in this Map

removeBlind

protected boolean removeBlind(java.lang.Object oKey)

Removes the mapping for this key from this map if present. This method exists to allow sub-classes to optmiize remove functionalitly for situations in which the original value is not required.

Overrides:

removeBlind in class AbstractKeyBasedMap

Parameters:

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

Returns:

true iff the Map changed as the result of this operation

getUnits

public int getUnits()

Determine the number of units that the cache currently stores.

Note: It is expected that the return type will be widened to a long in Coherence 4.

Specified by:

getUnits in interface ConfigurableCacheMap

Returns:

the current size of the cache in units

getHighUnits

public int getHighUnits()

Determine the limit of the cache size in units. The cache will prune itself automatically once it reaches its maximum unit level. This is often referred to as the "high water mark" of the cache.

Note: It is expected that the return type will be widened to a long in Coherence 4.

Specified by:

getHighUnits in interface ConfigurableCacheMap

Returns:

the limit of the cache size in units

setHighUnits

public void setHighUnits(int cMax)

Update the maximum size of the cache in units. This is often referred to as the "high water mark" of the cache.

Note: It is expected that the parameter will be widened to a long in Coherence 4.

Specified by:

setHighUnits in interface ConfigurableCacheMap

Parameters:

cMax - the new maximum size of the cache, in units

getLowUnits

public int getLowUnits()

Determine the point to which the cache will shrink when it prunes. This is often referred to as a "low water mark" of the cache. If the cache incrementally prunes, then this setting will have no effect.

Note: It is expected that the parameter will be widened to a long in Coherence 4.

Specified by:

getLowUnits in interface ConfigurableCacheMap

Returns:

the number of units that the cache prunes to

setLowUnits

public void setLowUnits(int cUnits)

Specify the point to which the cache will shrink when it prunes. This is often referred to as a "low water mark" of the cache.

Note: It is expected that the parameter will be widened to a long in Coherence 4.

Specified by:

setLowUnits in interface ConfigurableCacheMap

Parameters:

cUnits - the number of units that the cache prunes to

getUnitFactor

public int getUnitFactor()

Determine the factor by which the Units, LowUnits and HighUnits properties are adjusted. Using a binary unit calculator, for example, the factor 1048576 could be used to count megabytes instead of bytes.

Note: This property exists only to avoid changing the type of the units, low units and high units properties from 32-bit values to 64-bit values. It is expected that the parameter will be dropped in Coherence 4.

Specified by:

getUnitFactor in interface ConfigurableCacheMap

Returns:

the units factor; the default is 1

setUnitFactor

public void setUnitFactor(int nFactor)

Determine the factor by which the Units, LowUnits and HighUnits properties are adjusted. Using a binary unit calculator, for example, the factor 1048576 could be used to count megabytes instead of bytes.

Note: This property exists only to avoid changing the type of the units, low units and high units properties from 32-bit values to 64-bit values. It is expected that the parameter will be dropped in Coherence 4.

Specified by:

setUnitFactor in interface ConfigurableCacheMap

Parameters:

nFactor - the units factor; the default is 1

evict

public void evict(java.lang.Object oKey)

Evict a specified key from the cache, as if it had expired from the cache. If the key is not in the cache, then the method has no effect.

Specified by:

evict in interface ConfigurableCacheMap

Parameters:

oKey - the key to evict from the cache

evictAll

public void evictAll(java.util.Collection colKeys)

Evict the specified keys from the cache, as if they had each expired from the cache.

The result of this method is defined to be semantically the same as the following implementation:

 for (Iterator iter = colKeys.iterator(); iter.hasNext(); )
     {
     Object oKey = iter.next();
     evict(oKey);
     }
 

Specified by:

evictAll in interface ConfigurableCacheMap

Parameters:

colKeys - a collection of keys to evict from the cache

evict

public void evict()

Evict all entries from the cache that are no longer valid, and potentially prune the cache size if the cache is size-limited and its size is above the caching low water mark.

Specified by:

evict in interface ConfigurableCacheMap

getEvictionApprover

public ConfigurableCacheMap.EvictionApprover getEvictionApprover()

Obtain the registered EvictionApprover.

Specified by:

getEvictionApprover in interface ConfigurableCacheMap

Returns:

the EvictionApprover (could be null)

setEvictionApprover

public void setEvictionApprover(ConfigurableCacheMap.EvictionApprover approver)

Set the EvictionApprover for this ConfigurableCacheMap.

Specified by:

setEvictionApprover in interface ConfigurableCacheMap

Parameters:

approver - the EvictionApprover

getExpiryDelay

public int getExpiryDelay()

Determine the default "time to live" for each individual cache entry.

Specified by:

getExpiryDelay in interface ConfigurableCacheMap

Returns:

the number of milliseconds that a cache entry value will live, or zero if cache entries are never automatically expired

setExpiryDelay

public void setExpiryDelay(int cMillis)

Specify the default "time to live" for cache entries. This does not affect the already-scheduled expiry of existing entries.

Specified by:

setExpiryDelay in interface ConfigurableCacheMap

Parameters:

cMillis - the number of milliseconds that cache entries will live, or zero to disable automatic expiry

getCacheEntry

public ConfigurableCacheMap.Entry getCacheEntry(java.lang.Object oKey)

Locate a cache Entry in the cache based on its key.

Specified by:

getCacheEntry in interface ConfigurableCacheMap

Parameters:

oKey - the key object to search for

Returns:

the Entry or null

getEvictionPolicy

public ConfigurableCacheMap.EvictionPolicy getEvictionPolicy()

Obtain the current EvictionPolicy used by the cache.

Specified by:

getEvictionPolicy in interface ConfigurableCacheMap

Returns:

the EvictionPolicy used by the cache

getInternalEvictionPolicy

protected CompactSerializationCache.InternalEvictionPolicy getInternalEvictionPolicy()

Return the InternalEvictionPolicy used by this CompactSerializationCache.

Note: this method returns the actual instance of EvictionPolicy being used by this cache, which may differ in implementation from the configured policy returned by getEvictionPolicy().

Returns:

the internal eviction policy

setEvictionPolicy

public void setEvictionPolicy(ConfigurableCacheMap.EvictionPolicy policy)

Set the EvictionPolicy for the cache to use.

Specified by:

setEvictionPolicy in interface ConfigurableCacheMap

Parameters:

policy - an EvictionPolicy

getUnitCalculator

public ConfigurableCacheMap.UnitCalculator getUnitCalculator()

Obtain the current UnitCalculator used by the cache.

Specified by:

getUnitCalculator in interface ConfigurableCacheMap

Returns:

the UnitCalculator used by the cache

setUnitCalculator

public void setUnitCalculator(ConfigurableCacheMap.UnitCalculator calculator)

Set the UnitCalculator for the cache to use.

Specified by:

setUnitCalculator in interface ConfigurableCacheMap

Parameters:

calculator - a UnitCalculator

addMapListener

public void addMapListener(MapListener listener)

Add a standard map listener that will receive all events (inserts, updates, deletes) that occur against the map, with the key, old-value and new-value included. This has the same result as the following call:

   addMapListener(listener, (Filter) null, false);
 

Specified by:

addMapListener in interface ObservableMap

Parameters:

listener - the MapEvent listener to add

removeMapListener

public void removeMapListener(MapListener listener)

Remove a standard map listener that previously signed up for all events. This has the same result as the following call:

   removeMapListener(listener, (Filter) null);
 

Specified by:

removeMapListener in interface ObservableMap

Parameters:

listener - the listener to remove

addMapListener

public void addMapListener(MapListener listener,
                           java.lang.Object oKey,
                           boolean fLite)

Add a map listener for a specific key.

The listeners will receive MapEvent objects, but if fLite is passed as true, they might not contain the OldValue and NewValue properties.

To unregister the MapListener, use the ObservableMap.removeMapListener(MapListener, Object) method.

Specified by:

addMapListener in interface ObservableMap

Parameters:

listener - the MapEvent listener to add

oKey - the key that identifies the entry for which to raise events

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

removeMapListener

public void removeMapListener(MapListener listener,
                              java.lang.Object oKey)

Remove a map listener that previously signed up for events about a specific key.

Specified by:

removeMapListener in interface ObservableMap

Parameters:

listener - the listener to remove

oKey - the key that identifies the entry for which to raise events

addMapListener

public void addMapListener(MapListener listener,
                           Filter filter,
                           boolean fLite)

Add a map listener that receives events based on a filter evaluation.

The listeners will receive MapEvent objects, but if fLite is passed as true, they might not contain the OldValue and NewValue properties.

To unregister the MapListener, use the ObservableMap.removeMapListener(MapListener, Filter) method.

Specified by:

addMapListener in interface ObservableMap

Parameters:

listener - the MapEvent listener to add

filter - a filter that will be passed MapEvent objects to select from; a MapEvent will be delivered to the listener only if the filter evaluates to true for that MapEvent (see MapEventFilter); null is equivalent to a filter that alway returns true

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

removeMapListener

public void removeMapListener(MapListener listener,
                              Filter filter)

Remove a map listener that previously signed up for events based on a filter evaluation.

Specified by:

removeMapListener in interface ObservableMap

Parameters:

listener - the listener to remove

filter - the filter that was passed into the corresponding addMapListener() call

dispose

public void dispose()

Specified by:

dispose in interface com.oracle.common.base.Disposable

instantiateDeferredCacheEvent

protected CompactSerializationCache.DeferredCacheEvent instantiateDeferredCacheEvent(int nId,
                                                                                     Binary binKey,
                                                                                     java.lang.Object oKey,
                                                                                     java.lang.Object oValueOld,
                                                                                     java.lang.Object oValueNew,
                                                                                     boolean fSynthetic)

Create a DeferredCacheEvent object with the provided arguments. The oValueOld may be null as the deferred event may call load upon request.

Parameters:

nId - this event's id, one of MapEvent.ENTRY_INSERTED, MapEvent.ENTRY_UPDATED or MapEvent.ENTRY_DELETED

binKey - the binary key into the map

oKey - the key into the map

oValueOld - optional old value (for update and delete events); if not provided a call to getOldValue will load the old value from the BinaryStore

oValueNew - the new value (for insert and update events)

fSynthetic - true iff the event is caused by the cache internal processing such as eviction or loading

Returns:

a DeferredCacheEvent object

dispatchEvent

protected void dispatchEvent(int nId,
                             Binary binKey,
                             java.lang.Object oKey,
                             java.lang.Object oValueOld,
                             java.lang.Object oValueNew,
                             boolean fSynthetic)

Dispatch the passed event.

Parameters:

nId - this event's id, one of MapEvent.ENTRY_INSERTED, MapEvent.ENTRY_UPDATED or MapEvent.ENTRY_DELETED

binKey - the binary key into the map

oKey - the key into the map

oValueOld - optional old value (for update and delete events); if not provided a call to getOldValue will load the old value from the BinaryStore

oValueNew - the new value (for insert and update events)

fSynthetic - true iff the event is caused by the cache internal processing such as eviction or loading

toString

public java.lang.String toString()

Returns a string representation of this Map. The string representation consists of a list of key-value mappings in the order returned by the Map's entrySet view's iterator, enclosed in braces ("{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to strings as by String.valueOf(Object).

Overrides:

toString in class AbstractKeyBasedMap

Returns:

a String representation of this Map

removeInternal

protected java.lang.Object removeInternal(java.lang.Object oKey,
                                          Binary binKey,
                                          boolean fBlind)

Remove the given key from the BinaryStore only loading the value if necessary.

Parameters:

oKey - the key to be removed

binKey - the binary key to be removed

fBlind - whether the remove should be blind

Returns:

the previous value or an indicator (OBJECT_EXISTS) to suggest the object did exist if fBlind is true

configureEviction

protected void configureEviction()

Ensure that the BinaryLongMaps required for eviction support are configured.

ensureExpiryMap

protected BinaryLongMap ensureExpiryMap()

Ensure that the expiry-map is initialized.

Returns:

the expiry map

checkExpiry

protected void checkExpiry(boolean fForce)

Check the cache entries for expiration, removing expired entries as necessary.

Parameters:

fForce - pass true to force the expiry check, or false to only run it if it hasn't been run in a while

checkExpiry

protected void checkExpiry(Binary binKey)

Check the specified key to see if it is expired, removing it if necessary. This method will also ensure that other cache entries which are ripe for expiration will eventually be expired before too many accumulate.

Parameters:

binKey - the key to check for expiration

checkSize

protected void checkSize()

Check the current size of the cache to see that it is within the configured high-units, evicting entries according to the configured ConfigurableCacheMap.EvictionPolicy if necessary.

checkSize

protected void checkSize(boolean fCheckExpiry)

Check the current size of the cache to see that it is within the configured high-units, evicting entries according to the configured ConfigurableCacheMap.EvictionPolicy if necessary.

Parameters:

fCheckExpiry - true iff the expiry should be checked if eviction is called for

touch

protected void touch(Binary binKey)

Register a "touch" of the specified key.

Parameters:

binKey - the key that was touched

evictInternal

protected int evictInternal(Binary binKey)

Attempt to evict the cache entry for the specified key from the cache as a result of either expiration or size-triggered eviction, returning the unit-size of the evicted entry, or 0 if the eviction was disallowed by the ConfigurableCacheMap.EvictionApprover.

Parameters:

binKey - the key to evict

Returns:

the number of units evicted

registerExpiry

protected void registerExpiry(Binary binKey,
                              long cExpiry)

Register the expiry for the specified key.

Parameters:

binKey - the key

cExpiry - the number of milliseconds until the cache entry will expire, also referred to as the entry's "time to live" or 0 to indicate that the cache entry should never expire

getEntryUnits

protected int getEntryUnits(Binary binKey)

Return the unit-size of the entry associated with the specified key, or 0 if the key does not exist.

Parameters:

binKey - the key

Returns:

the unit-size of the entry associated with the specified key

calculateUnits

protected int calculateUnits(Binary binKey,
                             Binary binValue)

Calculate the unit cost of the specified cache entry, according to the configured unit-calculator.

Parameters:

binKey - the key

binValue - the value

Returns:

the unit cost of the cache entry

updateUnits

protected void updateUnits(Binary binKey,
                           int cUnits)

Update the units associated with the specified key.

Parameters:

binKey - the key

cUnits - the units

toBinary

protected Binary toBinary(java.lang.Object o)

Translate the passed Object object into an Binary object.

Parameters:

o - the Object to serialize into a Binary object

Returns:

the Binary object

fromBinary

protected java.lang.Object fromBinary(Binary bin)

Translate the passed Binary object into an Object object.

Parameters:

bin - the Binary object to deserialize

Returns:

the deserialized object

getCacheEntryInternal

protected ConfigurableCacheMap.Entry getCacheEntryInternal(Binary binKey)

Return a ConfigurableCacheMap.Entry for the specified key.

Parameters:

binKey - the binary or "raw" form of the key

Returns:

an Entry representing the specified key

getCacheEntryInternal

protected ConfigurableCacheMap.Entry getCacheEntryInternal(Binary binKey,
                                                           java.lang.Object oKey)

Return a ConfigurableCacheMap.Entry for the specified key.

Parameters:

binKey - the binary or "raw" form of the key

oKey - the Object or "natural" form of the key

Returns:

an Entry representing the specified key

toExternalUnits

protected static int toExternalUnits(long cUnits,
                                     int nFactor)

Convert from an internal 64-bit unit value to an external 32-bit unit value using the configured units factor.

Parameters:

cUnits - an internal 64-bit units value

nFactor - the unit factor

Returns:

an external 32-bit units value

toInternalUnits

protected static long toInternalUnits(int cUnits,
                                      int nFactor)

Convert from an external 32-bit unit value to an internal 64-bit unit value using the configured units factor.

Parameters:

cUnits - an external 32-bit units value

Returns:

an internal 64-bit units value

encodeExpiry

protected long encodeExpiry(long cExpiryDelay)

Encode the specified expiry delay (relative to current time) into the internal format. The value can be decoded to yield an absolute date-time that is approximately equivalent to the the specified delay from the current time.

Parameters:

cExpiryDelay - the relative delay from the current time; must be >= 0

Returns:

the encoded expiry value

decodeExpiry

protected long decodeExpiry(long cExpiryEncoded)

Decode the specified encoded expiry value into an absolute time.

Parameters:

cExpiryEncoded - the encoded expiry value

Returns:

the absolute expiry time

encodeTime

protected int encodeTime(long ldt)

Encode the specified time into an opaque 32-bit value.

Parameters:

ldt - the time to encode

Returns:

the encoded time

decodeTime

protected long decodeTime(int cEncoded)

Decode the specified encoded time into an absolute ldt.

Parameters:

cEncoded - the 32-bit encoded time

Returns:

the absolute date-time

Skip navigation links