Type Parameters:: K - the type of keys maintained by this map; V - the type of mapped values

All Superinterfaces:: Map<K,V>

All Known Implementing Classes:: BlockingHashMap

public interface BlockingMap<K,V>
extends Map<K,V>

A Blocking Map

Blocking map is a Map that additionally supports operations that wait for a key to be available when retrieving an element. Blocking map acts as a synchronizer between producers and consumers.

BlockingMap methods come in three forms, with different ways of handling operations that cannot be satisfied immediately, but may be satisfied at some point in the future: one returns a special value, the second blocks the current thread indefinitely until the operation can succeed, and the third blocks for only a given maximum time limit before giving up. These methods are summarized in the following table:

	Special value	Blocks	Times out
Insert	`put(key, value)`	`offer(key, value)`	`offer(key, value, time, unit)`
Remove	`remove(key)`	`take(key)`	`take(key, time, unit)`
Examine	`get()`	not applicable	not applicable

A BlockingMap does not accept null elements. Implementations throw NullPointerException on attempts to put or offer a null. A null is used as a sentinel value to indicate failure of get and take operations.

A BlockingMap may be capacity bounded. At any given time it may have a remainingCapacity beyond which no additional elements can be put without blocking. A BlockingQueue without any intrinsic capacity constraints always reports a remaining capacity of Integer.MAX_VALUE.

BlockingMap implementations are designed to be used primarily for producer-consumer queues, but additionally support the Collection interface. So, for example, it is possible to put a group of key-value pairs to a map using putAll(map). However, such operations are in general not performed very efficiently, and are intended for only occasional use.

BlockingMap implementations are thread-safe. All queuing methods achieve their effects atomically using internal locks or other forms of concurrency control. However, the bulk Collection operations addAll, containsAll, retainAll and removeAll are not necessarily performed atomically unless specified otherwise in an implementation. So it is possible, for example, for putAll(map) to fail (throwing an exception) after adding only some of the elements in map.

A BlockingMap does not intrinsically support any kind of "close" or "shutdown" operation to indicate that no more items will be added. The needs and usage of such features tend to be implementation-dependent. For example, a common tactic is for producers to insert special end-of-stream or poison objects, that are interpreted accordingly when taken by consumers.

BlockingMap implementations generally do not define element-based versions of methods equals and hashCode but instead inherit the identity based versions from class Object, because element-based equality is not always well-defined for queues with the same elements but different ordering properties.

Producers cannot put(key, value)/offer(key, value) 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) Usage example, based on a typical producer-consumer scenario. Note that a BlockingMap can safely be used with multiple producers and multiple consumers.

Version:: 1.2, Semantics and contracts reviewed, 1.1, Semantics and contracts for a blocking map defined
Author:: Sarveswaran M

Nested Class Summary
- Nested classes/interfaces inherited from interface java.util.Map
  Map.Entry<K,V>

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`V`	`get(Object key)` Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
`boolean`	`isKeyAvailable(K key)` Returns `true` if this map contains a mapping for the specified key.
`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, 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.
`V`	`remove(Object key)` Removes the mapping for a key from this map if it is present.
`V`	`take(K 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(K key, long timeout, 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.

Methods inherited from interface java.util.Map
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, getOrDefault, hashCode, isEmpty, keySet, merge, putAll, putIfAbsent, remove, replace, replace, replaceAll, size, values

- Method Detail
  - isKeyAvailable
```
boolean isKeyAvailable(K key)
```
    Returns true if this map contains a mapping for the specified key.
    
    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:
    
    ClassCastException - if the key is of an inappropriate type for this map (optional)
  - get
```
V get(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 Map<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:
    
    ClassCastException - if the key is of an inappropriate type for this map (optional)
    
    NullPointerException - if the specified key is null and this map does not permit null keys (optional)
  - put
```
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 Map<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:
    
    UnsupportedOperationException - if the put operation is not supported by this map
    
    ClassCastException - if the class of the specified key or value prevents it from being stored in this map
    
    NullPointerException - if the specified key or value is null and this map does not permit null keys or values
    
    IllegalArgumentException - if some property of the specified key or value prevents it from being stored in this map
  - remove
```
V remove(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 Map<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:
    
    UnsupportedOperationException - if the remove operation is not supported by this map
    
    ClassCastException - if the key is of an inappropriate type for this map (optional)
    
    NullPointerException - if the specified key is null and this map does not permit null keys (optional)
  - offer
```
V offer(K key,
        V value)
 throws InterruptedException
```
    Associates the specified value with the specified key in this map.
    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)
    
    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:
    
    InterruptedException - if interrupted while waiting
    
    ClassCastException - if the class of the specified element prevents it from being added to this queue
    
    NullPointerException - if the specified element is null
    
    IllegalArgumentException - if some property of the specified element prevents it from being added to this queue
  - take
```
V take(K key)
throws InterruptedException
```
    Retrieves and removes the mapping for a key from this map if it is present, waiting if necessary until the mapping becomes available.
    
    Parameters:
    
    key - key whose mapping is to be removed from the map
    
    Returns:
    
    the previous value associated with key
    
    Throws:
    
    UnsupportedOperationException - if the remove operation is not supported by this map
    
    ClassCastException - if the key is of an inappropriate type for this map (optional)
    
    NullPointerException - if the specified key is null and this map does not permit null keys (optional)
    
    InterruptedException - if interrupted while waiting
  - offer
```
V offer(K key,
        V value,
        long timeout,
        TimeUnit unit)
 throws 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)
    
    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:
    
    InterruptedException - if interrupted while waiting
    
    ClassCastException - if the class of the specified element prevents it from being added to this queue
    
    NullPointerException - if the specified element is null
    
    IllegalArgumentException - if some property of the specified element prevents it from being added to this queue
  - take
```
V take(K key,
       long timeout,
       TimeUnit unit)
throws 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.
    
    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:
    
    UnsupportedOperationException - if the remove operation is not supported by this map
    
    ClassCastException - if the key is of an inappropriate type for this map (optional)
    
    NullPointerException - if the specified key is null and this map does not permit null keys (optional)
    
    InterruptedException - if interrupted while waiting

Interface BlockingMap<K,V>

A Blocking Map

Nested Class Summary

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

Method Summary

Methods inherited from interface java.util.Map

Method Detail

isKeyAvailable

get

put

remove

offer

take

offer

take