Interface EventuallyConsistentMap<K,V>
-
- All Superinterfaces:
DistributedPrimitive
public interface EventuallyConsistentMap<K,V> extends DistributedPrimitive
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.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.onosproject.store.service.DistributedPrimitive
DistributedPrimitive.Status, DistributedPrimitive.Type
-
-
Field Summary
-
Fields inherited from interface org.onosproject.store.service.DistributedPrimitive
DEFAULT_OPERATION_TIMEOUT_MILLIS
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method 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.V
compute(K key, BiFunction<K,V,V> recomputeFunction)
Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).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.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.default DistributedPrimitive.Type
primitiveType()
Returns the type of primitive.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.V
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.-
Methods inherited from interface org.onosproject.store.service.DistributedPrimitive
addStatusChangeListener, applicationId, destroy, name, removeStatusChangeListener, statusChangeListeners
-
-
-
-
Method Detail
-
primitiveType
default DistributedPrimitive.Type primitiveType()
Description copied from interface:DistributedPrimitive
Returns the type of primitive.- Specified by:
primitiveType
in interfaceDistributedPrimitive
- Returns:
- primitive type
-
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 anEventuallyConsistentMapListener
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 mapvalue
- the value to associate with the key in this map
-
remove
V remove(K key)
Removes the mapping associated with the specified key from the map.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- Returns:
- previous value associated with key, or null if there was no mapping for key.
-
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 the map's timestampProvider. 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 anEventuallyConsistentMapListener
if they are interested in receiving notification of updates to the map.- Parameters:
key
- the key to remove the mapping forvalue
- the value mapped to the key
-
compute
V compute(K key, BiFunction<K,V,V> recomputeFunction)
Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).If the function returns null, the mapping is removed (or remains absent if initially absent).
- Parameters:
key
- map keyrecomputeFunction
- function to recompute a new value- Returns:
- new value
-
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
-
-