org.apache.commons.collections.map
public final class StaticBucketMap extends Object implements Map
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 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 {@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 iterations and 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.
Since: Commons Collections 3.0 (previously in main package v2.1)
Version: $Revision: 1.11 $ $Date: 2004/02/18 01:13:19 $
Constructor Summary | |
---|---|
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 | |
---|---|
void | atomic(Runnable r)
Prevents any operations from occurring on this map while the
given {@link 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 | entrySet()
Gets the entry set.
|
boolean | equals(Object obj)
Compares this map to another, as per the Map specification.
|
Object | 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 | keySet()
Gets the key set.
|
Object | put(Object key, Object value)
Puts a new key value mapping into the map.
|
void | putAll(Map map)
Puts all the entries from the specified map into this map.
|
Object | remove(Object key)
Removes the specified key from the map.
|
int | size()
Gets the current size of the map.
|
Collection | values()
Gets the values.
|
Parameters: numBuckets the number of buckets for this map
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
Parameters: key the key to check
Returns: true if found
Parameters: value the value to check
Returns: true if found
Returns: the entry set
Parameters: obj the object to compare to
Returns: true if equal
Parameters: key the key to retrieve
Returns: the associated value
Returns: the hash code
Returns: true if empty
Returns: the key set
Parameters: key the key to use value the value to use
Returns: the previous mapping for the key
Parameters: map the map of entries to add
Parameters: key the key to remove
Returns: the previous value at this key
Returns: the current size
Returns: the values