Package org.apache.commons.collections4.map

# Class StaticBucketMap<K,V>

java.lang.Object
org.apache.commons.collections4.map.AbstractIterableMap<K,V>
org.apache.commons.collections4.map.StaticBucketMap<K,V>

Type Parameters:
  `K` - the type of the keys in this map
  `V` - the type of the values in this map

All Implemented Interfaces:
  `Map<K,V>`, `Get<K,V>`, `IterableGet<K,V>`, `IterableMap<K,V>`, `Put<K,V>`

public final class StaticBucketMap<K,V> extends AbstractIterableMap<K,V>
A StaticBucketMap is an efficient, thread-safe implementation of `Map` that performs well in a highly thread-contentious environment.

The map supports very efficient `get`, `put`, `remove` and `containsKey` operations, assuming (approximate) uniform hashing and that the number of entries does not exceed the number of buckets. If the number of entries exceeds the number of buckets or if the hash codes of the objects are not uniformly distributed, these operations have a worst case scenario that is proportional to the number of elements in the map (O(n)).

Each bucket in the hash table has its own monitor, so two threads can safely operate on the map at the same time, often without incurring any monitor contention. This means that you don't have to wrap instances of this class with `Collections.synchronizedMap(Map)`; instances are already thread-safe. Unfortunately, however, this means that this map implementation behaves in ways you may find disconcerting. Bulk operations, such as `putAll` or the `retainAll` operation in collection views, are not atomic. If two threads are simultaneously executing

       staticBucketMapInstance.putAll(map);

and

       staticBucketMapInstance.entrySet().removeAll(map.entrySet());

then the results are generally random. Those two statement could cancel each other out, leaving `staticBucketMapInstance` essentially unchanged, or they could leave some random subset of `map` in `staticBucketMapInstance`.

Also, much like an encyclopedia, the results of `size()` and `isEmpty()` are out-of-date as soon as they are produced.

The iterators returned by the collection views of this class are not fail-fast. They will never raise a `ConcurrentModificationException`. Keys and values added to the map after the iterator is created do not necessarily appear during iteration. Similarly, the iterator does not necessarily fail to return keys and values that were removed after the iterator was created.

Finally, unlike `HashMap`-style implementations, this class never rehashes the map. The number of buckets is fixed at construction time and never altered. Performance may degrade if you do not allocate enough buckets upfront.

The `atomic(Runnable)` method is provided to allow atomic iterations and bulk operations; however, overuse of `atomic` will basically result in a map that's slower than an ordinary synchronized `HashMap`.

Use this class if you do not require reliable bulk operations and iterations, or if you can make your own guarantees about how bulk operations will affect the map.

Since:
  3.0 (previously in main package v2.1)

- ## Nested Class Summary

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

  `Map.Entry<K,V>`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StaticBucketMap()`
  Initializes the map with the default number of buckets (255).
  `StaticBucketMap(int numBuckets)`
  Initializes the map with a specified number of buckets.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `atomic(Runnable runnable)`
  Prevents any operations from occurring on this map while the given `Runnable` executes.
  `void`
  `clear()`
  Clears the map of all entries.
  `boolean`
  `containsKey(Object key)`
  Checks if the map contains the specified key.
  `boolean`
  `containsValue(Object value)`
  Checks if the map contains the specified value.
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  Gets the entry set.
  `boolean`
  `equals(Object obj)`
  Compares this map to another, as per the Map specification.
  `V`
  `get(Object key)`
  Gets the value associated with the key.
  `int`
  `hashCode()`
  Gets the hash code, as per the Map specification.
  `boolean`
  `isEmpty()`
  Checks if the size is currently zero.
  `Set<K>`
  `keySet()`
  Gets the key set.
  `V`
  `put(K key, V value)`
  Puts a new key value mapping into the map.
  `void`
  `putAll(Map<? extends K,? extends V> map)`
  Puts all the entries from the specified map into this map.
  `V`
  `remove(Object key)`
  Removes the specified key from the map.
  `int`
  `size()`
  Gets the current size of the map.
  `Collection<V>`
  `values()`
  Gets the values.

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractIterableMap

  `mapIterator`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Constructor Details

  - ### StaticBucketMap

    public StaticBucketMap()
    Initializes the map with the default number of buckets (255).

  - ### StaticBucketMap

    public StaticBucketMap(int numBuckets)
    Initializes the map with a specified number of buckets. The number of buckets is never below 17, and is always an odd number (StaticBucketMap ensures this). The number of buckets is inversely proportional to the chances for thread contention. The fewer buckets, the more chances for thread contention. The more buckets the fewer chances for thread contention.
    Parameters:
      `numBuckets` - the number of buckets for this map

- ## Method Details

  - ### atomic

    public void atomic(Runnable runnable)
    Prevents any operations from occurring on this map while the given `Runnable` executes. This method can be used, for instance, to execute a bulk operation atomically:

         staticBucketMapInstance.atomic(new Runnable() {
             public void run() {
                 staticBucketMapInstance.putAll(map);
             }
         });

    It can also be used if you need a reliable iterator:

            staticBucketMapInstance.atomic(new Runnable() {
                public void run() {
                    Iterator iterator = staticBucketMapInstance.iterator();
                    while (iterator.hasNext()) {
                        foo(iterator.next();
                    }
                }
            });

    Implementation note: This method requires a lot of time and a ton of stack space. Essentially a recursive algorithm is used to enter each bucket's monitor. If you have twenty thousand buckets in your map, then the recursive method will be invoked twenty thousand times. You have been warned.

    Parameters:
      `runnable` - the code to execute atomically

  - ### clear

    public void clear()
    Clears the map of all entries.
    See Also:
      - `Map.clear()`

  - ### containsKey

    public boolean containsKey(Object key)
    Checks if the map contains the specified key.
    Parameters:
      `key` - the key to check
    Returns:
      true if found
    See Also:
      - `Map.containsKey(Object)`

  - ### containsValue

    public boolean containsValue(Object value)
    Checks if the map contains the specified value.
    Parameters:
      `value` - the value to check
    Returns:
      true if found
    See Also:
      - `Map.containsValue(Object)`

  - ### entrySet

    public Set<Map.Entry<K,V>> entrySet()
    Gets the entry set.
    Returns:
      the entry set
    See Also:
      - `Map.entrySet()`

  - ### equals

    public boolean equals(Object obj)
    Compares this map to another, as per the Map specification.
    Specified by:
      `equals` in interface `Map<K,V>`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `obj` - the object to compare to
    Returns:
      true if equal

  - ### get

    public V get(Object key)
    Gets the value associated with the key.
    Parameters:
      `key` - the key to retrieve
    Returns:
      the associated value
    See Also:
      - `Map.get(Object)`

  - ### hashCode

    public int hashCode()
    Gets the hash code, as per the Map specification.
    Specified by:
      `hashCode` in interface `Map<K,V>`
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code

  - ### isEmpty

    public boolean isEmpty()
    Checks if the size is currently zero.
    Returns:
      true if empty
    See Also:
      - `Map.isEmpty()`

  - ### keySet

    public Set<K> keySet()
    Gets the key set.
    Returns:
      the key set
    See Also:
      - `Map.keySet()`

  - ### put

    public V put(K key, V value)
    Puts a new key value mapping into the map.
    Parameters:
      `key` - the key to use
      `value` - the value to use
    Returns:
      the previous mapping for the key
    See Also:
      - `Map.put(Object, Object)`

  - ### putAll

    public void putAll(Map<? extends K,? extends V> map)
    Puts all the entries from the specified map into this map. This operation is not atomic and may have undesired effects.
    Parameters:
      `map` - the map of entries to add
    See Also:
      - `Map.putAll(Map)`

  - ### remove

    public V remove(Object key)
    Removes the specified key from the map.
    Parameters:
      `key` - the key to remove
    Returns:
      the previous value at this key
    See Also:
      - `Map.remove(Object)`

  - ### size

    public int size()
    Gets the current size of the map. The value is computed fresh each time the method is called.
    Returns:
      the current size
    See Also:
      - `Map.size()`

  - ### values

    public Collection<V> values()
    Gets the values.
    Returns:
      the values
    See Also:
      - `Map.values()`