| 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
StaticBucketMap.get(Object) get ,
StaticBucketMap.put(Object,Object) put ,
StaticBucketMap.remove(Object) remove and
StaticBucketMap.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
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
StaticBucketMap.putAll(Map) putAll or the
Collection.retainAll(Collection) 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
StaticBucketMap.size() and
StaticBucketMap.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
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
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
StaticBucketMap.atomic(Runnable) method is provided to allow atomic iterations
and bulk operations; however, overuse of
StaticBucketMap.atomic(Runnable) atomic will basically result in a map that's slower than an ordinary synchronized
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.
since:
Commons Collections 3.0 (previously in main package v2.1)
version:
$Revision: 348273 $ $Date: 2005-11-22 22:24:25 +0000 (Tue, 22 Nov 2005) $
author:
Berin Loritsch
author:
Gerhard Froehlich
author:
Michael A. Smith
author:
Paul Jack
author:
Leo Sutic
author:
Janek Bogucki
author:
Kazuya Ujihara |
