org.apache.commons.collections

## Class StaticBucketMap

- java.lang.Object
- - org.apache.commons.collections.StaticBucketMap

- All Implemented Interfaces:
    Map

  Deprecated.
  Moved to map subpackage. Due to be removed in v4.0.

      public final class StaticBucketMap
      extends Object
      implements Map

  A StaticBucketMap is an efficient, thread-safe implementation of `java.util.Map` that performs well in 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:
    Commons Collections 2.1
  Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Berin Loritsch, Gerhard Froehlich, Michael A. Smith, Paul Jack, Leo Sutic, Janek Bogucki, Kazuya Ujihara

- - ### Nested Class Summary

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

      `Map.Entry`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `atomic(Runnable r)` Deprecated. Prevents any operations from occurring on this map while the given `Runnable` executes.
    `void` | `clear()` Deprecated. Implements `Map.clear()`.
    `boolean` | `containsKey(Object key)` Deprecated. Implements `Map.containsKey(Object)`.
    `boolean` | `containsValue(Object value)` Deprecated. Implements `Map.containsValue(Object)`.
    `Set` | `entrySet()` Deprecated. Implements `Map.entrySet()`.
    `boolean` | `equals(Object obj)` Deprecated. Implements `Map.equals(Object)`.
    `Object` | `get(Object key)` Deprecated. Implements `Map.get(Object)`.
    `int` | `hashCode()` Deprecated. Implements `Map.hashCode()`.
    `boolean` | `isEmpty()` Deprecated. Implements `Map.isEmpty()`.
    `Set` | `keySet()` Deprecated. Implements `Map.keySet()`.
    `Object` | `put(Object key, Object value)` Deprecated. Implements `Map.put(Object, Object)`.
    `void` | `putAll(Map other)` Deprecated. Implements `Map.putAll(Map)`.
    `Object` | `remove(Object key)` Deprecated. Implements `Map.remove(Object)`.
    `int` | `size()` Deprecated. Implements `Map.size()`.
    `Collection` | `values()` Deprecated. Implements `Map.values()`.

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

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

- - ### Constructor Detail

    - #### StaticBucketMap

          public StaticBucketMap()

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

    - #### StaticBucketMap

          public StaticBucketMap(int numBuckets)

      Deprecated.
      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 Detail

    - #### keySet

          public Set keySet()

      Deprecated.
      Implements `Map.keySet()`.
      Specified by:
        `keySet` in interface `Map`

    - #### size

          public int size()

      Deprecated.
      Implements `Map.size()`.
      Specified by:
        `size` in interface `Map`

    - #### put

          public Object put(Object key,
                   Object value)

      Deprecated.
      Implements `Map.put(Object, Object)`.
      Specified by:
        `put` in interface `Map`

    - #### get

          public Object get(Object key)

      Deprecated.
      Implements `Map.get(Object)`.
      Specified by:
        `get` in interface `Map`

    - #### containsKey

          public boolean containsKey(Object key)

      Deprecated.
      Implements `Map.containsKey(Object)`.
      Specified by:
        `containsKey` in interface `Map`

    - #### containsValue

          public boolean containsValue(Object value)

      Deprecated.
      Implements `Map.containsValue(Object)`.
      Specified by:
        `containsValue` in interface `Map`

    - #### values

          public Collection values()

      Deprecated.
      Implements `Map.values()`.
      Specified by:
        `values` in interface `Map`

    - #### entrySet

          public Set entrySet()

      Deprecated.
      Implements `Map.entrySet()`.
      Specified by:
        `entrySet` in interface `Map`

    - #### putAll

          public void putAll(Map other)

      Deprecated.
      Implements `Map.putAll(Map)`.
      Specified by:
        `putAll` in interface `Map`

    - #### remove

          public Object remove(Object key)

      Deprecated.
      Implements `Map.remove(Object)`.
      Specified by:
        `remove` in interface `Map`

    - #### isEmpty

          public final boolean isEmpty()

      Deprecated.
      Implements `Map.isEmpty()`.
      Specified by:
        `isEmpty` in interface `Map`

    - #### clear

          public final void clear()

      Deprecated.
      Implements `Map.clear()`.
      Specified by:
        `clear` in interface `Map`

    - #### equals

          public final boolean equals(Object obj)

      Deprecated.
      Implements `Map.equals(Object)`.
      Specified by:
        `equals` in interface `Map`
      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public final int hashCode()

      Deprecated.
      Implements `Map.hashCode()`.
      Specified by:
        `hashCode` in interface `Map`
      Overrides:
        `hashCode` in class `Object`

    - #### atomic

          public void atomic(Runnable r)

      Deprecated.
      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:
        `r` - the code to execute atomically

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.