org.thavam.util.concurrent
Class BlockingHashMap<K,V>

java.lang.Object
  org.thavam.util.concurrent.BlockingHashMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Implemented Interfaces:

java.util.Map<K,V>, BlockingMap<K,V>

public class BlockingHashMap<K,V>
extends java.lang.Object
implements BlockingMap<K,V>

An unbound Blocking Map Visit Project Home for source

An unbound blocking map backed by a hashmap that is concurrent. This map offers no guarantee on the order of retrieval.

This is similar to "unbounded buffer", in which the synchronizer elements inserted by producers and extracted by consumers. The only twist is that each product has a key & consumers know which product they are interested in. Attempts to put/offer an element into the map will always succeed because this is an unbound map; attempts to take element corresponding to a key that is not available on the map will block.

This map can be shutdown using clear. All consumers blocked on the map while invoking clear will be throw InterruptedException or return with null. Attempting any operation after shutdown will throw IllegalStateException.

This class implements some of optional methods of the Map.

Nested Class Summary

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

java.util.Map.Entry<K,V>

Constructor Summary

BlockingHashMap()

Method Summary

void	clear() Shuts down this blocking map & removes all mappings from this map.
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined
V	get(java.lang.Object key) Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
boolean	isKeyAvailable(K key) Returns true if this map contains a mapping for the specified key.
java.util.Set<K>	keySet() Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined
V	offer(K key, V value) Associates the specified value with the specified key in this map.
V	offer(K key, V value, long timeout, java.util.concurrent.TimeUnit unit) Associates the specified value with the specified key in this map.
V	put(K key, V value) Associates the specified value with the specified key in this map.
void	putAll(java.util.Map<? extends K,? extends V> m) To be supported
V	remove(java.lang.Object key) Removes the mapping for a key from this map if it is present.
int	size() Returns the number of key-value mappings in this map
V	take(java.lang.Object key) Retrieves and removes the mapping for a key from this map if it is present, waiting if necessary until the mapping becomes available.
V	take(java.lang.Object key, long timeout, java.util.concurrent.TimeUnit unit) Retrieves and removes the mapping for a key from this map if it is present, waiting if necessary until the mapping becomes available or the specified time elapses.
java.util.Collection<V>	values() Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

BlockingHashMap

public BlockingHashMap()

Method Detail

isKeyAvailable

public boolean isKeyAvailable(K key)

Returns true if this map contains a mapping for the specified key.

Specified by:

isKeyAvailable in interface BlockingMap<K,V>

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map

java.lang.NullPointerException - if the specified key is null

java.lang.IllegalStateException - if the map has been shut-down

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map<K,V>

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

java.lang.IllegalStateException - if the map has been shut-down

get

public V get(java.lang.Object key)

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

Note that null is used as a special marker to indicate the absence of the requested key

Specified by:

get in interface java.util.Map<K,V>

Specified by:

get in interface BlockingMap<K,V>

Parameters:

key - the key whose associated value is to be returned

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

java.lang.IllegalStateException - if the map has been shut-down

put

public V put(K key,
             V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified value.

If the Map is bounded and there is no space to put the new mapping, this method returns with null. put on an unbound map will always succeed

Producers cannot put on a key that is already available on the map. Attempts to put a mapping whose key is already available on the map are ignored. However, the same mapping can be put in to the map after it is taken by consumer(s)

Specified by:

put in interface java.util.Map<K,V>

Specified by:

put in interface BlockingMap<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that there is no space available on map)

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map

java.lang.NullPointerException - if the specified key or value is null and this map does not permit null keys or values

java.lang.IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map

remove

public V remove(java.lang.Object key)

Removes the mapping for a key from this map if it is present.

Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key.

The map will not contain a mapping for the specified key once the call returns.

Specified by:

remove in interface java.util.Map<K,V>

Specified by:

remove in interface BlockingMap<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key.

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this map

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

java.lang.IllegalStateException - if the map has been shut-down

offer

public V offer(K key,
               V value)
        throws java.lang.InterruptedException

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified value.

If the Map is bounded and there is no space to put the new mapping, this method blocks till space becomes available. offer on an unbound map will always succeed

Producers cannot offer a mapping on a key that is already available on the map. Attempts to such a mapping are ignored. However, the same mapping can be successfully offered after the existing mapping is taken by consumer(s)

Specified by:

offer in interface BlockingMap<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate that there is no space available on map)

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null

java.lang.IllegalArgumentException - if some property of the specified element prevents it from being added to this queue

take

public V take(java.lang.Object key)
       throws java.lang.InterruptedException

Retrieves and removes the mapping for a key from this map if it is present, waiting if necessary until the mapping becomes available.

Specified by:

take in interface BlockingMap<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key.

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this map

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

java.lang.InterruptedException - if interrupted while waiting

java.lang.IllegalStateException - if the map has been shut-down

offer

public V offer(K key,
               V value,
               long timeout,
               java.util.concurrent.TimeUnit unit)
        throws java.lang.InterruptedException

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified value.

If the Map is bounded and there is no space to put the new mapping, this method blocks till space becomes available or the specified time elapses. offer on an unbound map will always succeed

Producers cannot offer a mapping on a key that is already available on the map. Attempts to such a mapping are ignored. However, the same mapping can be successfully offered after the existing mapping is taken by consumer(s)

Specified by:

offer in interface BlockingMap<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the previous value associated with key, or null if there was no mapping for key. (A null return can also indicate a time out

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null

java.lang.IllegalArgumentException - if some property of the specified element prevents it from being added to this queue

java.lang.IllegalStateException - if the map has been shut-down

take

public V take(java.lang.Object key,
              long timeout,
              java.util.concurrent.TimeUnit unit)
       throws java.lang.InterruptedException

Retrieves and removes the mapping for a key from this map if it is present, waiting if necessary until the mapping becomes available or the specified time elapses. offer on an unbound map will always succeed.

Specified by:

take in interface BlockingMap<K,V>

Parameters:

key - key with which the specified value is to be associated

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the

Returns:

the previous value associated with key, or null if there was no mapping for key and the call times out.

Throws:

java.lang.UnsupportedOperationException - if the remove operation is not supported by this map

java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional)

java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional)

java.lang.InterruptedException - if interrupted while waiting

java.lang.IllegalStateException - if the map has been shut-down

clear

public void clear()

Shuts down this blocking map & removes all mappings from this map. The map will be empty after this call returns.

Interrupts any threads waiting on any key in map before clearing. This is done to prevent threads being blocked forever

Specified by:

clear in interface java.util.Map<K,V>

Throws:

java.lang.IllegalStateException - if the map has been shut-down

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value.

Specified by:

containsValue in interface java.util.Map<K,V>

Parameters:

value - value whose presence in this map is to be tested

Returns:

true if this map maps one or more keys to the specified value

Throws:

java.lang.IllegalStateException - if the map has been shut-down

java.lang.UnsupportedOperationException

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map<K,V>

Returns:

true if this map contains no key-value mappings

size

public int size()

Returns the number of key-value mappings in this map

Specified by:

size in interface java.util.Map<K,V>

Returns:

the number of key-value mappings in this map

Throws:

java.lang.IllegalStateException - if the map has been shut-down

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined

Specified by:

entrySet in interface java.util.Map<K,V>

Throws:

java.lang.IllegalStateException - if the map has been shut-down

java.lang.UnsupportedOperationException

keySet

public java.util.Set<K> keySet()

Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined

Specified by:

keySet in interface java.util.Map<K,V>

Throws:

java.lang.IllegalStateException - if the map has been shut-down

java.lang.UnsupportedOperationException

values

public java.util.Collection<V> values()

Not supported Semantics of addition/removal to map outside the producer/consumer methods not defined

Specified by:

values in interface java.util.Map<K,V>

Throws:

java.lang.IllegalStateException - if the map has been shut-down

java.lang.UnsupportedOperationException

putAll

public void putAll(java.util.Map<? extends K,? extends V> m)

To be supported

Specified by:

putAll in interface java.util.Map<K,V>

Throws:

java.lang.UnsupportedOperationException

java.lang.IllegalStateException - if the map has been shut-down