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 {@link #get(Object) get}, {@link #put(Object,Object) put}, {@link #remove(Object) remove} and {@link #containsKey(Object) 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 {@link java.util.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 {@link #putAll(Map) putAll} or the{@link Collection#retainAll(Collection) retainAll} operation in collectionviews, 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 {@link #size()} and{@link #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 {@link java.util.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 {@link java.util.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 {@link #atomic(Runnable)} method is provided to allow atomic iterationsand bulk operations; however, overuse of {@link #atomic(Runnable) atomic}will basically result in a map that's slower than an ordinary synchronized {@link java.util.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.
@author Berin Loritsch
@author Gerhard Froehlich
@author Michael A. Smith
@author Paul Jack
@author Leo Sutic
@author Matt Hall, John Watkinson, Janek Bogucki
@version $Revision: 1.1 $ $Date: 2005/10/11 17:05:32 $
@since Commons Collections 3.0 (previously in main package v2.1)