EventuallyConsistentMap (onos-core-dist 1.1.0 API)

All Known Implementing Classes:

EventuallyConsistentMapImpl
```
public interface EventuallyConsistentMap<K,V>
```
A distributed, eventually consistent map.
This map does not offer read after writes consistency. Operations are serialized via the timestamps issued by the clock service. If two updates are in conflict, the update with the more recent timestamp will endure.
The interface is mostly similar to Map with some minor semantic changes and the addition of a listener framework (because the map can be mutated by clients on other instances, not only through the local Java API).
Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notifications of update to the map.
Null values are not allowed in this map.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addListener(EventuallyConsistentMapListener<K,V> listener)` Adds the specified listener to the map which will be notified whenever the mappings in the map are changed.
`void`	`clear()` Removes all mappings from this map.
`boolean`	`containsKey(K key)` Returns true if the map contains a mapping for the specified key.
`boolean`	`containsValue(V value)` Returns true if the map contains a mapping from any key to the specified value.
`void`	`destroy()` Shuts down the map and breaks communication between different instances.
`Set<Map.Entry<K,V>>`	`entrySet()` Returns a set of mappings contained in this map.
`V`	`get(K key)` Returns the value mapped to the specified key.
`boolean`	`isEmpty()` Returns true if this map is empty.
`Set<K>`	`keySet()` Returns a set of the keys in this map.
`void`	`put(K key, V value)` Associates the specified value to the specified key in this map.
`void`	`putAll(Map<? extends K,? extends V> m)` Adds mappings for all key-value pairs in the specified map to this map.
`void`	`remove(K key)` Removes the mapping associated with the specified key from the map.
`void`	`remove(K key, V value)` Removes the given key-value mapping from the map, if it exists.
`void`	`removeListener(EventuallyConsistentMapListener<K,V> listener)` Removes the specified listener from the map such that it will no longer receive change notifications.
`int`	`size()` Returns the number of key-value mappings in this map.
`Collection<V>`	`values()` Returns a collections of values in this map.

- Method Detail
  - size
```
int size()
```
    Returns the number of key-value mappings in this map.
    
    Returns:
    
    number of key-value mappings
  - isEmpty
```
boolean isEmpty()
```
    Returns true if this map is empty.
    
    Returns:
    
    true if this map is empty, otherwise false
  - containsKey
```
boolean containsKey(K key)
```
    Returns true if the map contains a mapping for the specified key.
    
    Parameters:
    
    key - the key to check if this map contains
    
    Returns:
    
    true if this map has a mapping for the key, otherwise false
  - containsValue
```
boolean containsValue(V value)
```
    Returns true if the map contains a mapping from any key to the specified value.
    
    Parameters:
    
    value - the value to check if this map has a mapping for
    
    Returns:
    
    true if this map has a mapping to this value, otherwise false
  - get
```
V get(K key)
```
    Returns the value mapped to the specified key.
    
    Parameters:
    
    key - the key to look up in this map
    
    Returns:
    
    the value mapped to the key, or null if no mapping is found
  - put
```
void put(K key,
         V value)
```
    Associates the specified value to the specified key in this map.
    Note: this differs from the specification of Map because it does not return the previous value associated with the key. Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.
    Null values are not allowed in the map.
    
    Parameters:
    
    key - the key to add a mapping for in this map
    
    value - the value to associate with the key in this map
  - remove
```
void remove(K key)
```
    Removes the mapping associated with the specified key from the map.
    Note: this differs from the specification of Map because it does not return the previous value associated with the key. Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.
    
    Parameters:
    
    key - the key to remove the mapping for
  - remove
```
void remove(K key,
            V value)
```
    Removes the given key-value mapping from the map, if it exists.
    This actually means remove any values up to and including the timestamp given by ClockService.getTimestamp(Object, Object). Any mappings that produce an earlier timestamp than this given key-value pair will be removed, and any mappings that produce a later timestamp will supersede this remove.
    Note: this differs from the specification of Map because it does not return a boolean indication whether a value was removed. Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.
    
    Parameters:
    
    key - the key to remove the mapping for
    
    value - the value mapped to the key
  - putAll
```
void putAll(Map<? extends K,? extends V> m)
```
    Adds mappings for all key-value pairs in the specified map to this map.
    This will be more efficient in communication than calling individual put operations.
    
    Parameters:
    
    m - a map of values to add to this map
  - clear
```
void clear()
```
    Removes all mappings from this map.
  - keySet
```
Set<K> keySet()
```
    Returns a set of the keys in this map. Changes to the set are not reflected back to the map.
    
    Returns:
    
    set of keys in the map
  - values
```
Collection<V> values()
```
    Returns a collections of values in this map. Changes to the collection are not reflected back to the map.
    
    Returns:
    
    collection of values in the map
  - entrySet
```
Set<Map.Entry<K,V>> entrySet()
```
    Returns a set of mappings contained in this map. Changes to the set are not reflected back to the map.
    
    Returns:
    
    set of key-value mappings in this map
  - addListener
```
void addListener(EventuallyConsistentMapListener<K,V> listener)
```
    Adds the specified listener to the map which will be notified whenever the mappings in the map are changed.
    
    Parameters:
    
    listener - listener to register for events
  - removeListener
```
void removeListener(EventuallyConsistentMapListener<K,V> listener)
```
    Removes the specified listener from the map such that it will no longer receive change notifications.
    
    Parameters:
    
    listener - listener to deregister for events
  - destroy
```
void destroy()
```
    Shuts down the map and breaks communication between different instances. This allows the map objects to be cleaned up and garbage collected. Calls to any methods on the map subsequent to calling destroy() will throw a RuntimeException.

Interface EventuallyConsistentMap<K,V>

Method Summary

Method Detail

size

isEmpty

containsKey

containsValue

get

put

remove

remove

putAll

clear

keySet

values

entrySet

addListener

removeListener

destroy