org.onosproject.store.service

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, DEFAULT_OPERTATION_TIMEOUT_MILLIS

Method Summary

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.
V	compute(K key, java.util.function.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.
java.util.Set<java.util.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.
java.util.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(java.util.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.
java.util.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 interface DistributedPrimitive

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 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

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 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

compute

V compute(K key,
          java.util.function.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 key

recomputeFunction - function to recompute a new value

Returns:

new value

putAll

void putAll(java.util.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

java.util.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

java.util.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

java.util.Set<java.util.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