Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.util
Class SafeHashMap

    java.lang.Object
      java.util.AbstractMap
          com.tangosol.util.SafeHashMap

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, java.util.Map

Direct Known Subclasses:
  ObservableHashMap, OldCache

    public class SafeHashMap

extends java.util.AbstractMap
implements java.lang.Cloneable, java.io.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 1999.04.27

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 a factor of four.
`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 100%, which means that the hash map will not resize until there is (on average) one entry in every bucket.
`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 java.lang.Object` | `m_oIterActive` A holder for active Iterator(s): either WeakReference() or WeakHashMap(, null)
`protected SafeHashMap.EntrySet` | `m_setEntries` 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 java.lang.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.
`java.lang.Object` | `clone()` Create a clone of the SafeHashMap.
`protected SafeHashMap.Entry` | `cloneEntryList(SafeHashMap.Entry entryThat)` Clone an entire linked list of entries.
`boolean` | `containsKey(java.lang.Object key)` Returns `true` if this map contains a mapping for the specified key.
`java.util.Set` | `entrySet()` Returns a set view of the mappings contained in this map.
`java.lang.Object` | `get(java.lang.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(java.lang.Object key)` Locate an Entry in the hash map based on its key.
`protected SafeHashMap.Entry` | `getEntryInternal(java.lang.Object oKey)` Locate an Entry in the hash map based on its key.
`protected SafeHashMap.Entry[]` | `getStableBucketArray()` Get the bucket array, or if a resize is occurring, wait for the resize to complete and return the new bucket array.
`protected void` | `grow()` Resize the bucket array, rehashing all Entries.
`protected SafeHashMap.Entry` | `instantiateEntry()` Factory pattern: instantiate an un-initialized Entry object.
`protected SafeHashMap.Entry` | `instantiateEntry(java.lang.Object oKey, java.lang.Object oValue, int iHash)` Factory pattern: instantiate initialized Entry object.
`protected SafeHashMap.EntrySet` | `instantiateEntrySet()` Factory pattern.
`protected SafeHashMap.KeySet` | `instantiateKeySet()` Factory pattern.
`protected SafeHashMap.ValuesCollection` | `instantiateValuesCollection()` Factory pattern.
`protected boolean` | `isActiveIterator()` Determine if there are any active Iterators, which may mean that they are in the middle of iterating over the Map.
`boolean` | `isEmpty()` Returns `true` if this map contains no key-value mappings.
`protected void` | `iteratorActivated(java.util.Iterator iter)` Register the activation of an Iterator.
`protected void` | `iteratorDeactivated(java.util.Iterator iter)` Unregister the (formerly active) Iterator.
`java.util.Set` | `keySet()` Returns a Set view of the keys contained in this map.
`java.lang.Object` | `put(java.lang.Object key, java.lang.Object value)` Associates the specified value with the specified key in this map.
`java.lang.Object` | `remove(java.lang.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.
`java.util.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

### PRIME_MODULO

    protected static final int[] PRIME_MODULO

  A list of possible modulos to use.

### 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.)

### BIGGEST_MODULO

    protected static final int BIGGEST_MODULO

  Biggest possible modulo.

### DEFAULT_LOADFACTOR

    public static final float DEFAULT_LOADFACTOR

  The default load factor is 100%, which means that the hash map will not resize until there is (on average) one entry in every bucket. The cost of scanning a linked list in a particular bucket is very low, so there is little reason for having this value below 1.0, and the goal is constant order access, so assuming a perfect hash this will provide the optimal access speed relative to size.

  See Also:
    Constant Field Values

### DEFAULT_GROWTHRATE

    public static final float DEFAULT_GROWTHRATE

  Using the default growth rate, the bucket array will grow by a factor of four. The relatively high growth rate helps to ensure less resize operations, an important consideration in a high-concurrency map.

  See Also:
    Constant Field Values

### RESIZING

    protected java.lang.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_setEntries

    protected transient SafeHashMap.EntrySet m_setEntries

  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.

### m_oIterActive

    protected transient java.lang.Object m_oIterActive

  A holder for active Iterator(s): either WeakReference() or WeakHashMap(, null)

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 `java.util.Map`
  Overrides:
    `size` in class `java.util.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 `java.util.Map`
  Overrides:
    `isEmpty` in class `java.util.AbstractMap`
  Returns:
    `true` if this map contains no key-value mappings

### containsKey

    public boolean containsKey(java.lang.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 `java.util.Map`
  Overrides:
    `containsKey` in class `java.util.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 java.lang.Object get(java.lang.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 `java.util.Map`
  Overrides:
    `get` in class `java.util.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(java.lang.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 java.lang.Object put(java.lang.Object key,
                                java.lang.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 `java.util.Map`
  Overrides:
    `put` in class `java.util.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 java.lang.Object remove(java.lang.Object oKey)

  Removes the mapping for this key from this map if present.

  Specified by:
    `remove` in interface `java.util.Map`
  Overrides:
    `remove` in class `java.util.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 `java.util.Map`
  Overrides:
    `clear` in class `java.util.AbstractMap`

### entrySet

    public java.util.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 `java.util.Map`
  Specified by:
    `entrySet` in class `java.util.AbstractMap`
  Returns:
    a set view of the mappings contained in this map.

### keySet

    public java.util.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 `java.util.Map`
  Overrides:
    `keySet` in class `java.util.AbstractMap`
  Returns:
    a Set view of the keys contained in this map

### values

    public java.util.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 `java.util.Map`
  Overrides:
    `values` in class `java.util.AbstractMap`
  Returns:
    a collection view of the values contained in this map

### clone

    public java.lang.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 `java.util.AbstractMap`
  Returns:
    a clone of the SafeHashMap

### cloneEntryList

    protected SafeHashMap.Entry cloneEntryList(SafeHashMap.Entry entryThat)

  Clone an entire linked list of entries.

  This method must be called on the map that will contain the clones, to allow the map to be the parent of the entries if the entries are not static inner classes.

  Parameters:
    `entryThat` - the entry that is the head of the list to clone
  Returns:
    null if the entry is null, otherwise an entry that is a clone of the passed entry, and a linked list of clones for each entry in the linked list that was passed

### getEntryInternal

    protected SafeHashMap.Entry getEntryInternal(java.lang.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

### getStableBucketArray

    protected SafeHashMap.Entry[] getStableBucketArray()

  Get the bucket array, or if a resize is occurring, wait for the resize to complete and return the new bucket array.

  Returns:
    the latest bucket array

### iteratorActivated

    protected void iteratorActivated(java.util.Iterator iter)

  Register the activation of an Iterator.

  Parameters:
    `iter` - the activated iterator

### iteratorDeactivated

    protected void iteratorDeactivated(java.util.Iterator iter)

  Unregister the (formerly active) Iterator.

  Parameters:
    `iter` - the deactivated iterator

### isActiveIterator

    protected boolean isActiveIterator()

  Determine if there are any active Iterators, which may mean that they are in the middle of iterating over the Map.

  Returns:
    true iff there is at least one active Iterator

### instantiateEntry

    protected SafeHashMap.Entry instantiateEntry(java.lang.Object oKey,
                                                 java.lang.Object oValue,
                                                 int iHash)

  Factory pattern: instantiate initialized Entry object.

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

### instantiateEntry

    protected SafeHashMap.Entry instantiateEntry()

  Factory pattern: instantiate an un-initialized Entry object.

  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)

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.