CoherenceTM v3.1.3
Copyright© 2000-2006 by Tangosol, Inc.

com.tangosol.util
Class SafeHashMap

java.lang.Object
  extended by java.util.AbstractMap
      extended by com.tangosol.util.SafeHashMap
All Implemented Interfaces:
Serializable, Cloneable, Map
Direct Known Subclasses:
ObservableHashMap, OldCache

public class SafeHashMap
extends AbstractMap
implements Cloneable, Serializable

An implementation of java.util.Map that is synchronized, but minimally so. This class is for use in situation where high concurrency is required, but so is data integrity. All additions and removals are synchronized on the map, so to temporarily prevent changes to the map contents, synchronize on the map object.

Author:
cp 04/27/99

Nested Class Summary
protected static class SafeHashMap.Entry
          A map entry (key-value pair).
protected  class SafeHashMap.EntrySet
          A set of entries backed by this map.
protected  class SafeHashMap.KeySet
          A set of entries backed by this map.
protected  class SafeHashMap.ValuesCollection
          A collection of values backed by this map.
 
Field Summary
protected static int BIGGEST_MODULO
          Biggest possible modulo.
static float DEFAULT_GROWTHRATE
          Using the default growth rate, the bucket array will grow by almost a factor of two and a half.
static int DEFAULT_INITIALSIZE
          Default initial size provides a prime modulo and is large enough that resize is not immediate.
static float DEFAULT_LOADFACTOR
          The default load factor is roughly 80%, theoretically a good trade-off between size and speed, and high enough to prevent unneccessary resizing.
protected  SafeHashMap.Entry[] m_aeBucket
          The array of hash buckets.
protected  int m_cCapacity
          The capacity of the hash map (the point at which it must resize), 1 <= n.
protected  int m_cEntries
          The number of entries stored in the hash map, 0 <= n.
protected  SafeHashMap.ValuesCollection m_colValues
          The collection of values backed by this map.
protected  float m_flGrowthRate
          The rate of growth as a fraction of the current number of buckets, 0 < n, such that the hash map grows to bucketcount * (1 + growthrate)
protected  float m_flLoadFactor
          The determining factor for the hash map capacity given a certain number of buckets, such that capactiy = bucketcount * loadfactor.
protected  SafeHashMap.EntrySet m_set
          The set of entries backed by this map.
protected  SafeHashMap.KeySet m_setKeys
          The set of keys backed by this map.
protected static int[] PRIME_MODULO
          A list of possible modulos to use.
protected  Object RESIZING
          When resizing completes, a notification is issued against this object.
 
Constructor Summary
SafeHashMap()
          Construct a thread-safe hash map using the default settings.
SafeHashMap(int cInitialBuckets, float flLoadFactor, float flGrowthRate)
          Construct a thread-safe hash map using the specified settings.
 
Method Summary
 void clear()
          Removes all mappings from this map.
 Object clone()
          Create a clone of the SafeHashMap.
 boolean containsKey(Object key)
          Returns true if this map contains a mapping for the specified key.
 Set entrySet()
          Returns a set view of the mappings contained in this map.
 Object get(Object key)
          Returns the value to which this map maps the specified key.
protected  int getBucketIndex(int nHash, int cBuckets)
          Calculate the bucket number for a particular hash code.
 SafeHashMap.Entry getEntry(Object key)
          Locate an Entry in the hash map based on its key.
protected  SafeHashMap.Entry getEntryInternal(Object oKey)
          Locate an Entry in the hash map based on its key.
protected  void grow()
          Resize the bucket array, rehashing all Entries.
protected  SafeHashMap.Entry instantiateEntry()
          Factory pattern.
protected  SafeHashMap.EntrySet instantiateEntrySet()
          Factory pattern.
protected  SafeHashMap.KeySet instantiateKeySet()
          Factory pattern.
protected  SafeHashMap.ValuesCollection instantiateValuesCollection()
          Factory pattern.
 boolean isEmpty()
          Returns true if this map contains no key-value mappings.
 Set keySet()
          Returns a Set view of the keys contained in this map.
 Object put(Object key, Object value)
          Associates the specified value with the specified key in this map.
 Object remove(Object oKey)
          Removes the mapping for this key from this map if present.
protected  void removeEntryInternal(SafeHashMap.Entry entry)
          Removes the passed Entry from the map.
 int size()
          Returns the number of key-value mappings in this map.
 Collection values()
          Returns a collection view of the values contained in this map.
 
Methods inherited from class java.util.AbstractMap
containsValue, equals, hashCode, putAll, toString
 

Field Detail

DEFAULT_INITIALSIZE

public static final int DEFAULT_INITIALSIZE
Default initial size provides a prime modulo and is large enough that resize is not immediate. (A hash map probably uses less than 128 bytes initially.)

See Also:
Constant Field Values

DEFAULT_LOADFACTOR

public static final float DEFAULT_LOADFACTOR
The default load factor is roughly 80%, theoretically a good trade-off between size and speed, and high enough to prevent unneccessary resizing.

See Also:
Constant Field Values

DEFAULT_GROWTHRATE

public static final float DEFAULT_GROWTHRATE
Using the default growth rate, the bucket array will grow by almost a factor of two and a half. The relatively high growth rate helps to ensure less resize operations, an important consideration in a high- concurrency map.

See Also:
Constant Field Values

PRIME_MODULO

protected static final int[] PRIME_MODULO
A list of possible modulos to use.


BIGGEST_MODULO

protected static final int BIGGEST_MODULO
Biggest possible modulo.


RESIZING

protected Object RESIZING
When resizing completes, a notification is issued against this object.

Due to custom serialization this field cannot be marked as "final", but must be treated as such.


m_cEntries

protected volatile int m_cEntries
The number of entries stored in the hash map, 0 <= n. This field is declared volatile to avoid synchronization for the size() operation.


m_aeBucket

protected volatile SafeHashMap.Entry[] m_aeBucket
The array of hash buckets. This field is declared volatile in order to reduce synchronization.


m_cCapacity

protected int m_cCapacity
The capacity of the hash map (the point at which it must resize), 1 <= n.


m_flLoadFactor

protected float m_flLoadFactor
The determining factor for the hash map capacity given a certain number of buckets, such that capactiy = bucketcount * loadfactor.


m_flGrowthRate

protected float m_flGrowthRate
The rate of growth as a fraction of the current number of buckets, 0 < n, such that the hash map grows to bucketcount * (1 + growthrate)


m_set

protected transient SafeHashMap.EntrySet m_set
The set of entries backed by this map.


m_setKeys

protected transient SafeHashMap.KeySet m_setKeys
The set of keys backed by this map.


m_colValues

protected transient SafeHashMap.ValuesCollection m_colValues
The collection of values backed by this map.

Constructor Detail

SafeHashMap

public SafeHashMap()
Construct a thread-safe hash map using the default settings.


SafeHashMap

public SafeHashMap(int cInitialBuckets,
                   float flLoadFactor,
                   float flGrowthRate)
Construct a thread-safe hash map using the specified settings.

Parameters:
cInitialBuckets - the initial number of hash buckets, 0 < n
flLoadFactor - the acceptable load factor before resizing occurs, 0 < n, such that a load factor of 1.0 causes resizing when the number of entries exceeds the number of buckets
flGrowthRate - the rate of bucket growth when a resize occurs, 0 < n, such that a growth rate of 1.0 will double the number of buckets: bucketcount = bucketcount * (1 + growthrate)
Method Detail

size

public int size()
Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. This method is not synchronized; it returns the size at the moment that the method is invoked. To ensure that the size does not change from the returned value, the caller must synchronize on the map before calling the size method.

Specified by:
size in interface Map
Overrides:
size in class AbstractMap
Returns:
the number of key-value mappings in this map

isEmpty

public boolean isEmpty()
Returns true if this map contains no key-value mappings. This method is not synchronized; it returns the state of the map at the moment that the method is invoked. To ensure that the size does not change, the caller must synchronize on the map before calling the method.

Specified by:
isEmpty in interface Map
Overrides:
isEmpty in class AbstractMap
Returns:
true if this map contains no key-value mappings

containsKey

public boolean containsKey(Object key)
Returns true if this map contains a mapping for the specified key. This method is not synchronized; it returns true if the map contains the key at the moment that the method is invoked. To ensure that the key is still in (or is still not in) the table when the method returns, the caller must synchronize on the map before calling the method.

Specified by:
containsKey in interface Map
Overrides:
containsKey in class AbstractMap
Parameters:
key - key whose presence in this map is to be tested
Returns:
true if this map contains a mapping for the specified key

get

public Object get(Object key)
Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

Specified by:
get in interface Map
Overrides:
get in class AbstractMap
Parameters:
key - key whose associated value is to be returned
Returns:
the value to which this map maps the specified key, or null if the map contains no mapping for this key

getEntry

public SafeHashMap.Entry getEntry(Object key)
Locate an Entry in the hash map based on its key.

Parameters:
key - the key object to search for
Returns:
the Entry or null

put

public Object put(Object key,
                  Object value)
Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced. This method is not synchronized; it only synchronizes internally if it has to add a new Entry. To ensure that the value does not change (or the Entry is not removed) before this method returns, the caller must synchronize on the map before calling this method.

Specified by:
put in interface Map
Overrides:
put in class AbstractMap
Parameters:
key - key with which the specified value is to be associated
value - 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

grow

protected void grow()
Resize the bucket array, rehashing all Entries.


remove

public Object remove(Object oKey)
Removes the mapping for this key from this map if present.

Specified by:
remove in interface Map
Overrides:
remove in class AbstractMap
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()
Removes all mappings from this map.

Specified by:
clear in interface Map
Overrides:
clear in class AbstractMap

entrySet

public Set entrySet()
Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
entrySet in interface Map
Specified by:
entrySet in class AbstractMap
Returns:
a set view of the mappings contained in this map.

keySet

public Set keySet()
Returns a Set view of the keys contained in this map. The Set is backed by the map, so changes to the map are reflected in the Set, and vice-versa. (If the map is modified while an iteration over the Set is in progress, the results of the iteration are undefined.) The Set supports element removal, which removes the corresponding entry from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:
keySet in interface Map
Overrides:
keySet in class AbstractMap
Returns:
a Set view of the keys contained in this map

values

public Collection values()
Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
values in interface Map
Overrides:
values in class AbstractMap
Returns:
a collection view of the values contained in this map

clone

public Object clone()
Create a clone of the SafeHashMap. Synchronization is necessary to prevent resizing (or to wait for resizing to complete), and also prevents other changes to the SafeHashMap while the deep clone is occurring.

Overrides:
clone in class AbstractMap
Returns:
a clone of the SafeHashMap

getEntryInternal

protected SafeHashMap.Entry getEntryInternal(Object oKey)
Locate an Entry in the hash map based on its key.

Unlike the getEntry(java.lang.Object) method, there must be no side-effects of calling this method.

Parameters:
oKey - the key object to search for
Returns:
the Entry or null

removeEntryInternal

protected void removeEntryInternal(SafeHashMap.Entry entry)
Removes the passed Entry from the map.

Note: Unlike calling the "remove" method, which is overriden at subclasses, calling this method directly does not generate any events.

Parameters:
entry - the entry to remove from this map

getBucketIndex

protected int getBucketIndex(int nHash,
                             int cBuckets)
Calculate the bucket number for a particular hash code.

Parameters:
nHash - the hash code
cBuckets - the number of buckets
Returns:
the bucket index for the specified hash code

instantiateEntry

protected SafeHashMap.Entry instantiateEntry()
Factory pattern.

Returns:
a new instance of the Entry class (or a subclass thereof)

instantiateEntrySet

protected SafeHashMap.EntrySet instantiateEntrySet()
Factory pattern.

Returns:
a new instance of the EntrySet class (or a subclass thereof)

instantiateKeySet

protected SafeHashMap.KeySet instantiateKeySet()
Factory pattern.

Returns:
a new instance of the KeySet class (or subclass thereof)

instantiateValuesCollection

protected SafeHashMap.ValuesCollection instantiateValuesCollection()
Factory pattern.

Returns:
a new instance of the ValuesCollection class (or subclass thereof)

CoherenceTM v3.1.3
Copyright© 2000-2006 by Tangosol, Inc.