Package org.apache.commons.collections

Class StaticBucketMap

  • All Implemented Interfaces:
    java.util.Map
    @Deprecated(since="2021-04-30")
public final class StaticBucketMap
extends java.lang.Object
implements java.util.Map
    Deprecated.
    Moved to map subpackage. Due to be removed in v4.0.
    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

    • Nested Class Summary

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

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Constructor Summary

      Constructors 
      Constructor 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

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

      • Methods inherited from class java.lang.Object

        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 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 java.util.Set keySet()
        Deprecated.
        Implements Map.keySet().
        Specified by:
        keySet in interface java.util.Map

      • size

        public int size()
        Deprecated.
        Implements Map.size().
        Specified by:
        size in interface java.util.Map

      • put

        public java.lang.Object put​(java.lang.Object key,
                            java.lang.Object value)
        Deprecated.
        Implements Map.put(Object, Object).
        Specified by:
        put in interface java.util.Map

      • get

        public java.lang.Object get​(java.lang.Object key)
        Deprecated.
        Implements Map.get(Object).
        Specified by:
        get in interface java.util.Map

      • containsKey

        public boolean containsKey​(java.lang.Object key)
        Deprecated.
        Implements Map.containsKey(Object).
        Specified by:
        containsKey in interface java.util.Map

      • containsValue

        public boolean containsValue​(java.lang.Object value)
        Deprecated.
        Implements Map.containsValue(Object).
        Specified by:
        containsValue in interface java.util.Map

      • values

        public java.util.Collection values()
        Deprecated.
        Implements Map.values().
        Specified by:
        values in interface java.util.Map

      • entrySet

        public java.util.Set entrySet()
        Deprecated.
        Implements Map.entrySet().
        Specified by:
        entrySet in interface java.util.Map

      • putAll

        public void putAll​(java.util.Map other)
        Deprecated.
        Implements Map.putAll(Map).
        Specified by:
        putAll in interface java.util.Map

      • remove

        public java.lang.Object remove​(java.lang.Object key)
        Deprecated.
        Implements Map.remove(Object).
        Specified by:
        remove in interface java.util.Map

      • isEmpty

        public final boolean isEmpty()
        Deprecated.
        Implements Map.isEmpty().
        Specified by:
        isEmpty in interface java.util.Map

      • clear

        public final void clear()
        Deprecated.
        Implements Map.clear().
        Specified by:
        clear in interface java.util.Map

      • equals

        public final boolean equals​(java.lang.Object obj)
        Deprecated.
        Implements Map.equals(Object).
        Specified by:
        equals in interface java.util.Map
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public final int hashCode()
        Deprecated.
        Implements Map.hashCode().
        Specified by:
        hashCode in interface java.util.Map
        Overrides:
        hashCode in class java.lang.Object

      • atomic

        public void atomic​(java.lang.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