com.tangosol.util

Class WrapperConcurrentMap<K,V>

java.lang.Object

com.tangosol.util.Base

com.tangosol.util.AbstractKeyBasedMap<K,V>

com.tangosol.util.AbstractKeySetBasedMap<K,V>

com.tangosol.util.WrapperObservableMap<K,V>

com.tangosol.util.WrapperConcurrentMap<K,V>

All Implemented Interfaces:

ConcurrentMap<K,V>, ObservableMap<K,V>, Map<K,V>

Direct Known Subclasses:

WrapperNamedCache

public class WrapperConcurrentMap<K,V>
extends WrapperObservableMap<K,V>
implements ConcurrentMap<K,V>

A simple implementation of ConcurrentMap interface built as a wrapper around any Map implementation. As a subclass of WrapperObservableMap, it naturally implements the ObservableMap interface and provides an implementation of CacheStatistics interface.

Author:

gg 2002.04.02

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	WrapperConcurrentMap.Lock A lock object.

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

WrapperObservableMap.InternalListener

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

AbstractKeySetBasedMap.EntrySet, AbstractKeySetBasedMap.KeyIterator, AbstractKeySetBasedMap.KeySet, AbstractKeySetBasedMap.ValuesCollection

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

AbstractKeyBasedMap.DeferredCacheEvent<K,V>

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

Base.LoggingWriter, Base.StackFrame

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

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected long	m_cWaitMillis The number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.
protected boolean	m_fEnforceLocking Flag indicating whether or not the locking is enforced for put, remove and clear operations.
protected Gate	m_gateMap The ThreadGate object for the entire map.
protected SafeHashMap	m_mapLock The map containing all the locks.

Fields inherited from class com.tangosol.util.WrapperObservableMap

m_fDeferredEvent, m_fTranslateEvents, m_listenerInternal, m_listenerSupport, m_map, m_stats

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Fields inherited from interface com.tangosol.util.ConcurrentMap

LOCK_ALL

Constructor Summary

Constructors

Constructor and Description
WrapperConcurrentMap(Map<K,V> map) Construct a ConcurrentMap wrapper based on the specified map with locking enforced for put, remove and clear operations.
WrapperConcurrentMap(Map<K,V> map, boolean fEnforceLocking, long cWaitMillis) Construct a ConcurrentMap wrapper based on the specified map.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear all key/value mappings.
protected String	getDescription() Assemble a human-readable description.
String	getLockDescription(Object oKey) Make a human-readable description of the information kept about the passed key.
long	getWaitMillis() Return the number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.
protected WrapperConcurrentMap.Lock	instantiateLock(Object oKey) Factory pattern.
protected boolean	isInternalKeySetIteratorMutable() Determine if this Iterator should remove an iterated item by calling remove on the internal key Set Iterator, or by calling removeBlind on the map itself.
boolean	isLockingEnforced() Obtain the flag indicating whether or not the locking is enforced for put, remove and clear operations.
boolean	lock(Object oKey) Attempt to lock the specified item and return immediately.
boolean	lock(Object oKey, long cWait) Attempt to lock the specified item within the specified period of time.
V	put(K oKey, V oValue) Associates the specified value with the specified key in this map.
void	putAll(Map<? extends K,? extends V> map) Copies all of the mappings from the specified map to this map.
V	remove(Object oKey) Removes the mapping for this key from this map if present.
protected boolean	removeBlind(Object oKey) Removes the mapping for this key from this map if present.
void	setLockingEnforced(boolean fEnforce) Set the flag indicating whether or not the locking is enforced for put, remove and clear operations.
void	setWaitMillis(long cWaitMillis) Specify the number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.
String	toString() Returns a string representation of this Map.
boolean	unlock(Object oKey) Unlock the specified item.

Methods inherited from class com.tangosol.util.WrapperObservableMap

addMapListener, addMapListener, addMapListener, containsValue, dispatchEvent, dispatchPendingEvent, ensureInternalListener, ensureMapListenerSupport, equals, get, getCacheStatistics, getInternalKeySet, getMap, getMapListenerSupport, hashCode, hasListeners, instantiateInternalListener, isCollectStats, isEventFabricator, isSynthetic, isTranslateEvents, removeMapListener, removeMapListener, removeMapListener, setCollectStats, setTranslateEvents

Methods inherited from class com.tangosol.util.AbstractKeySetBasedMap

containsKey, instantiateEntrySet, instantiateKeyIterator, instantiateKeySet, instantiateValues, isEmpty, iterateKeys, size

Methods inherited from class com.tangosol.util.AbstractKeyBasedMap

clone, entrySet, getAll, keySet, values

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getProcessRandom, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.tangosol.util.ConcurrentMap

containsKey, containsValue, get, isEmpty, size

Methods inherited from interface java.util.Map

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

Field Detail

m_fEnforceLocking

protected boolean m_fEnforceLocking

Flag indicating whether or not the locking is enforced for put, remove and clear operations.

m_cWaitMillis

protected long m_cWaitMillis

The number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.

m_mapLock

protected final SafeHashMap m_mapLock

The map containing all the locks.

m_gateMap

protected final Gate m_gateMap

The ThreadGate object for the entire map.

Constructor Detail

WrapperConcurrentMap

public WrapperConcurrentMap(Map<K,V> map)

Construct a ConcurrentMap wrapper based on the specified map with locking enforced for put, remove and clear operations.

Note: it is assumed that while the WrapperConcurrentMap exists, there is no direct manipulation with the content of the wrapped map.

Parameters:

map - the Map that will be wrapped by this WrapperConcurrentMap

WrapperConcurrentMap

public WrapperConcurrentMap(Map<K,V> map,
                            boolean fEnforceLocking,
                            long cWaitMillis)

Construct a ConcurrentMap wrapper based on the specified map.

Note: it is assumed that while the WrapperConcurrentMap exists, there is no direct manipulation with the content of the wrapped map.

Parameters:

map - the Map that will be wrapped by this WrapperConcurrentMap

fEnforceLocking - if true the locking is enforced for put, remove and clear operations; otherwise a client is responsible for calling lock and unlock explicitly

cWaitMillis - if locking enforcement is required then this parameter specifies the number of milliseconds to continue trying to obtain a lock; pass -1 to block the calling thread until the lock could be obtained

Method Detail

lock

public boolean lock(Object oKey,
                    long cWait)

Attempt to lock the specified item within the specified period of time.

The item doesn't have to exist to be locked. While the item is locked there is known to be a lock holder which has an exclusive right to modify (calling put and remove methods) that item.

Lock holder is an abstract concept that depends on the ConcurrentMap implementation. For example, holder could be a cluster member or a thread (or both).

Locking strategy may vary for concrete implementations as well. Lock could have an expiration time (this lock is sometimes called a "lease") or be held indefinitely (until the lock holder terminates).

Some implementations may allow the entire map to be locked. If the map is locked in such a way, then only a lock holder is allowed to perform any of the "put" or "remove" operations. Pass the special constant ConcurrentMap.LOCK_ALL as the oKey parameter to indicate the map lock.

Specified by:

lock in interface ConcurrentMap<K,V>

Parameters:

oKey - key being locked

cWait - the number of milliseconds to continue trying to obtain a lock; pass zero to return immediately; pass -1 to block the calling thread until the lock could be obtained

Returns:

true if the item was successfully locked within the specified time; false otherwise

lock

public boolean lock(Object oKey)

Attempt to lock the specified item and return immediately.

This method behaves exactly as if it simply performs the call lock(oKey, 0).

Specified by:

lock in interface ConcurrentMap<K,V>

Parameters:

oKey - key being locked

Returns:

true if the item was successfully locked; false otherwise

unlock

public boolean unlock(Object oKey)

Unlock the specified item. The item doesn't have to exist to be unlocked. If the item is currently locked, only the holder of the lock could successfully unlock it.

Specified by:

unlock in interface ConcurrentMap<K,V>

Parameters:

oKey - key being unlocked

Returns:

true if the item was successfully unlocked; false otherwise

clear

public void clear()

Clear all key/value mappings.

If lock enforcement is required an attempt will be made to lock the entire map using the ConcurrentMap.LOCK_ALL object.

Note: if this operation fails due to a ConcurrentModificationException, then any subset of the current mappings could still remain in the map.

Specified by:

clear in interface ConcurrentMap<K,V>

Specified by:

clear in interface Map<K,V>

Overrides:

clear in class WrapperObservableMap<K,V>

Throws:

ConcurrentModificationException - if any entry is locked by another thread

put

public V put(K oKey,
             V oValue)

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

Specified by:

put in interface ConcurrentMap<K,V>

Specified by:

put in interface Map<K,V>

Overrides:

put in class WrapperObservableMap<K,V>

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

Throws:

ConcurrentModificationException - if the entry is locked by another thread

putAll

public void putAll(Map<? extends K,? extends V> map)

Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling AbstractKeyBasedMap.put(K, V) on this map once for each mapping in the passed map. The behavior of this operation is unspecified if the passed map is modified while the operation is in progress.

Specified by:

putAll in interface ConcurrentMap<K,V>

Specified by:

putAll in interface Map<K,V>

Overrides:

putAll in class WrapperObservableMap<K,V>

Parameters:

map - the Map containing the key/value pairings to put into this Map

Throws:

ConcurrentModificationException - if the entry is locked by another thread

remove

public V remove(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 ConcurrentMap<K,V>

Specified by:

remove in interface Map<K,V>

Overrides:

remove in class WrapperObservableMap<K,V>

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.

Throws:

ConcurrentModificationException - if the entry is locked by another thread

isInternalKeySetIteratorMutable

protected boolean isInternalKeySetIteratorMutable()

Determine if this Iterator should remove an iterated item by calling remove on the internal key Set Iterator, or by calling removeBlind on the map itself.

Overrides:

isInternalKeySetIteratorMutable in class WrapperObservableMap<K,V>

Returns:

true to remove using the internal key Set Iterator or false to use the AbstractKeyBasedMap.removeBlind(Object) method

removeBlind

protected boolean removeBlind(Object oKey)

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

Overrides:

removeBlind in class WrapperObservableMap<K,V>

Parameters:

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

Returns:

true iff the Map changed as the result of this operation

Throws:

ConcurrentModificationException - if the entry is locked by another thread

toString

public 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 WrapperObservableMap<K,V>

Returns:

a String representation of this Map

isLockingEnforced

public boolean isLockingEnforced()

Obtain the flag indicating whether or not the locking is enforced for put, remove and clear operations.

Returns:

true if locking is enforced; false otherwise

setLockingEnforced

public void setLockingEnforced(boolean fEnforce)

Set the flag indicating whether or not the locking is enforced for put, remove and clear operations.

Parameters:

fEnforce - pass true to enforce locking; false otherwise

getWaitMillis

public long getWaitMillis()

Return the number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.

Returns:

the wait time in milliseconds

setWaitMillis

public void setWaitMillis(long cWaitMillis)

Specify the number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.

Parameters:

cWaitMillis - the wait time in milliseconds

getDescription

protected String getDescription()

Assemble a human-readable description.

Overrides:

getDescription in class WrapperObservableMap<K,V>

Returns:

a description of this Map

getLockDescription

public String getLockDescription(Object oKey)

Make a human-readable description of the information kept about the passed key.

Parameters:

oKey - the key

Returns:

the information known about the passed key

instantiateLock

protected WrapperConcurrentMap.Lock instantiateLock(Object oKey)

Factory pattern.

Parameters:

oKey - the key

Returns:

a new instance of the Lock class (or a subclass thereof)