Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.util
Class WrapperConcurrentMap

`java.lang.Object
com.tangosol.util.Base
com.tangosol.util.AbstractKeyBasedMap
com.tangosol.util.AbstractKeySetBasedMap
com.tangosol.util.WrapperObservableMap
com.tangosol.util.WrapperConcurrentMap`

All Implemented Interfaces:
  ConcurrentMap, ObservableMap, java.util.Map

Direct Known Subclasses:
  WrapperNamedCache

      public class WrapperConcurrentMap

extends WrapperObservableMap
implements ConcurrentMap

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
`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 interface java.util.Map
`java.util.Map.Entry`

Field Summary
`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 ThreadGate` | `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_fTranslateEvents, m_listenerInternal, m_listenerSupport, m_map, m_stats`

Fields inherited from interface com.tangosol.util.ConcurrentMap
`LOCK_ALL`

Constructor Summary
`WrapperConcurrentMap(java.util.Map map)` Construct a ConcurrentMap wrapper based on the specified map with locking enforced for put, remove and clear operations.
`WrapperConcurrentMap(java.util.Map map, boolean fEnforceLocking, long cWaitMillis)` Construct a ConcurrentMap wrapper based on the specified map.

Method Summary
`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.
`protected java.lang.String` | `getDescription()` Assemble a human-readable description.
`java.lang.String` | `getLockDescription(java.lang.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(java.lang.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 indicatinig whether or not the locking is enforced for put, remove and clear operations.
`boolean` | `lock(java.lang.Object oKey)` Attempt to lock the specified item and return immediately.
`boolean` | `lock(java.lang.Object oKey, long cWait)` Attempt to lock the specified item within the specified period of time.
`java.lang.Object` | `put(java.lang.Object oKey, java.lang.Object oValue)` Associates the specified value with the specified key in this map.
`void` | `putAll(java.util.Map 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(java.lang.Object, java.lang.Object)` 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.
`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.
`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.
`void` | `setLockingEnforced(boolean fEnforce)` Set the flag indicatinig whether or not the locking is enforced for put, remove and clear operations.
`void` | `setWaitMillis(long cWaitMillis)` Specifiy the number of milliseconds to continue trying to obtain a lock in case when the locking is enforced.
`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)`.
`boolean` | `unlock(java.lang.Object oKey)` Unlock the specified item.

Methods inherited from class com.tangosol.util.WrapperObservableMap
`addMapListener, addMapListener, addMapListener, containsValue, dispatchEvent, dispatchPendingEvent, ensureInternalListener, ensureMapListenerSupport, get, getCacheStatistics, getInternalKeySet, getMap, getMapListenerSupport, 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, equals, getAll, hashCode, keySet, values`

Methods inherited from interface com.tangosol.util.ConcurrentMap
`containsKey, containsValue, get, isEmpty, size`

Methods inherited from interface java.util.Map
`entrySet, equals, hashCode, keySet, 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 ThreadGate m_gateMap

  The ThreadGate object for the entire map.

Constructor Detail

### WrapperConcurrentMap

    public WrapperConcurrentMap(java.util.Map 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(java.util.Map 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 speicifes 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(java.lang.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`
  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(java.lang.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`
  Parameters:
    `oKey` - key being locked
  Returns:
    true if the item was successfully locked; false otherwise

### unlock

    public boolean unlock(java.lang.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`
  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`
  Specified by:
    `clear` in interface `java.util.Map`
  Overrides:
    `clear` in class `WrapperObservableMap`
  Throws:
    `java.util.ConcurrentModificationException` - if any entry is locked by another thread

### 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 `ConcurrentMap`
  Specified by:
    `put` in interface `java.util.Map`
  Overrides:
    `put` in class `WrapperObservableMap`
  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:
    `java.util.ConcurrentModificationException` - if the entry is locked by another thread

### putAll

    public void putAll(java.util.Map 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(java.lang.Object, java.lang.Object)` 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`
  Specified by:
    `putAll` in interface `java.util.Map`
  Overrides:
    `putAll` in class `WrapperObservableMap`
  Parameters:
    `map` - the Map containing the key/value pairings to put into this Map
  Throws:
    `java.util.ConcurrentModificationException` - if the entry is locked by another thread

### 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 `ConcurrentMap`
  Specified by:
    `remove` in interface `java.util.Map`
  Overrides:
    `remove` in class `WrapperObservableMap`
  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:
    `java.util.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`
  Returns:
    true to remove using the internal key Set Iterator or false to use the `AbstractKeyBasedMap.removeBlind(Object)` method

### 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 `WrapperObservableMap`
  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:
    `java.util.ConcurrentModificationException` - if the entry is locked by another thread

### 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 `WrapperObservableMap`
  Returns:
    a String representation of this Map

### isLockingEnforced

    public boolean isLockingEnforced()

  Obtain the flag indicatinig 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 indicatinig 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)

  Specifiy 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 java.lang.String getDescription()

  Assemble a human-readable description.
  Overrides:
    `getDescription` in class `WrapperObservableMap`
  Returns:
    a description of this Map

### getLockDescription

    public java.lang.String getLockDescription(java.lang.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(java.lang.Object oKey)

  Factory pattern.
  Returns:
    a new instance of the Lock class (or a subclass thereof)

Skip navigation links

Overview | Package | Class | Tree | Index | Help
| Oracle® Coherence Java API Reference Release 3.6.1.0 E18814-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.