org.onosproject.store.ecmap

Class EventuallyConsistentMapImpl<K,V>

java.lang.Object

org.onosproject.store.ecmap.EventuallyConsistentMapImpl<K,V>

All Implemented Interfaces:

EventuallyConsistentMap<K,V>

public class EventuallyConsistentMapImpl<K,V>
extends Object
implements EventuallyConsistentMap<K,V>

Distributed Map implementation which uses optimistic replication and gossip based techniques to provide an eventually consistent data store.

Constructor Summary

Constructors

Constructor and Description
EventuallyConsistentMapImpl(String mapName, org.onosproject.cluster.ClusterService clusterService, org.onosproject.store.cluster.messaging.ClusterCommunicationService clusterCommunicator, org.onlab.util.KryoNamespace.Builder serializerBuilder, ClockService<K,V> clockService) Creates a new eventually consistent map shared amongst multiple instances.
EventuallyConsistentMapImpl(String mapName, org.onosproject.cluster.ClusterService clusterService, org.onosproject.store.cluster.messaging.ClusterCommunicationService clusterCommunicator, org.onlab.util.KryoNamespace.Builder serializerBuilder, ClockService<K,V> clockService, java.util.function.BiFunction<K,V,Collection<org.onosproject.cluster.NodeId>> peerUpdateFunction) Creates a new eventually consistent map shared amongst multiple instances.

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.
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.
EventuallyConsistentMapImpl<K,V>	withBroadcastMessageExecutor(ExecutorService executor) Sets the executor to use for broadcasting messages and returns this instance for method chaining.
EventuallyConsistentMapImpl<K,V>	withTombstonesDisabled(boolean status)

Methods inherited from class java.lang.Object

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

Constructor Detail

EventuallyConsistentMapImpl

public EventuallyConsistentMapImpl(String mapName,
                                   org.onosproject.cluster.ClusterService clusterService,
                                   org.onosproject.store.cluster.messaging.ClusterCommunicationService clusterCommunicator,
                                   org.onlab.util.KryoNamespace.Builder serializerBuilder,
                                   ClockService<K,V> clockService,
                                   java.util.function.BiFunction<K,V,Collection<org.onosproject.cluster.NodeId>> peerUpdateFunction)

Creates a new eventually consistent map shared amongst multiple instances.

Each map is identified by a string map name. EventuallyConsistentMapImpl objects in different JVMs that use the same map name will form a distributed map across JVMs (provided the cluster service is aware of both nodes).

The client is expected to provide an KryoNamespace.Builder with which all classes that will be stored in this map have been registered (including referenced classes). This serializer will be used to serialize both K and V for inter-node notifications.

The client must provide an ClockService which can generate timestamps for a given key. The clock service is free to generate timestamps however it wishes, however these timestamps will be used to serialize updates to the map so they must be strict enough to ensure updates are properly ordered for the use case (i.e. in some cases wallclock time will suffice, whereas in other cases logical time will be necessary).

Parameters:

mapName - a String identifier for the map.

clusterService - the cluster service

clusterCommunicator - the cluster communications service

serializerBuilder - a Kryo namespace builder that can serialize both K and V

clockService - a clock service able to generate timestamps for K

peerUpdateFunction - function that provides a set of nodes to immediately update to when there writes to the map

EventuallyConsistentMapImpl

public EventuallyConsistentMapImpl(String mapName,
                                   org.onosproject.cluster.ClusterService clusterService,
                                   org.onosproject.store.cluster.messaging.ClusterCommunicationService clusterCommunicator,
                                   org.onlab.util.KryoNamespace.Builder serializerBuilder,
                                   ClockService<K,V> clockService)

Creates a new eventually consistent map shared amongst multiple instances.

Take a look at the other constructor for usage information. The only difference is that a BiFunction is provided that returns all nodes in the cluster, so all nodes will be sent write updates immediately.

Parameters:

mapName - a String identifier for the map.

clusterService - the cluster service

clusterCommunicator - the cluster communications service

serializerBuilder - a Kryo namespace builder that can serialize both K and V

clockService - a clock service able to generate timestamps for K

Method Detail

withTombstonesDisabled

public EventuallyConsistentMapImpl<K,V> withTombstonesDisabled(boolean status)

withBroadcastMessageExecutor

public EventuallyConsistentMapImpl<K,V> withBroadcastMessageExecutor(ExecutorService executor)

Sets the executor to use for broadcasting messages and returns this instance for method chaining.

Parameters:

executor - executor service

Returns:

this instance

size

public int size()

Description copied from interface: EventuallyConsistentMap

Returns the number of key-value mappings in this map.

Specified by:

size in interface EventuallyConsistentMap<K,V>

Returns:

number of key-value mappings

isEmpty

public boolean isEmpty()

Description copied from interface: EventuallyConsistentMap

Returns true if this map is empty.

Specified by:

isEmpty in interface EventuallyConsistentMap<K,V>

Returns:

true if this map is empty, otherwise false

containsKey

public boolean containsKey(K key)

Description copied from interface: EventuallyConsistentMap

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

Specified by:

containsKey in interface EventuallyConsistentMap<K,V>

Parameters:

key - the key to check if this map contains

Returns:

true if this map has a mapping for the key, otherwise false

containsValue

public boolean containsValue(V value)

Description copied from interface: EventuallyConsistentMap

Returns true if the map contains a mapping from any key to the specified value.

Specified by:

containsValue in interface EventuallyConsistentMap<K,V>

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

public V get(K key)

Description copied from interface: EventuallyConsistentMap

Returns the value mapped to the specified key.

Specified by:

get in interface EventuallyConsistentMap<K,V>

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

public void put(K key,
                V value)

Description copied from interface: EventuallyConsistentMap

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.

Specified by:

put in interface EventuallyConsistentMap<K,V>

Parameters:

key - the key to add a mapping for in this map

value - the value to associate with the key in this map

remove

public void remove(K key)

Description copied from interface: EventuallyConsistentMap

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.

Specified by:

remove in interface EventuallyConsistentMap<K,V>

Parameters:

key - the key to remove the mapping for

remove

public void remove(K key,
                   V value)

Description copied from interface: EventuallyConsistentMap

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.

Specified by:

remove in interface EventuallyConsistentMap<K,V>

Parameters:

key - the key to remove the mapping for

value - the value mapped to the key

putAll

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

Description copied from interface: EventuallyConsistentMap

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.

Specified by:

putAll in interface EventuallyConsistentMap<K,V>

Parameters:

m - a map of values to add to this map

clear

public void clear()

Description copied from interface: EventuallyConsistentMap

Removes all mappings from this map.

Specified by:

clear in interface EventuallyConsistentMap<K,V>

keySet

public Set<K> keySet()

Description copied from interface: EventuallyConsistentMap

Returns a set of the keys in this map. Changes to the set are not reflected back to the map.

Specified by:

keySet in interface EventuallyConsistentMap<K,V>

Returns:

set of keys in the map

values

public Collection<V> values()

Description copied from interface: EventuallyConsistentMap

Returns a collections of values in this map. Changes to the collection are not reflected back to the map.

Specified by:

values in interface EventuallyConsistentMap<K,V>

Returns:

collection of values in the map

entrySet

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

Description copied from interface: EventuallyConsistentMap

Returns a set of mappings contained in this map. Changes to the set are not reflected back to the map.

Specified by:

entrySet in interface EventuallyConsistentMap<K,V>

Returns:

set of key-value mappings in this map

addListener

public void addListener(EventuallyConsistentMapListener<K,V> listener)

Description copied from interface: EventuallyConsistentMap

Adds the specified listener to the map which will be notified whenever the mappings in the map are changed.

Specified by:

addListener in interface EventuallyConsistentMap<K,V>

Parameters:

listener - listener to register for events

removeListener

public void removeListener(EventuallyConsistentMapListener<K,V> listener)

Description copied from interface: EventuallyConsistentMap

Removes the specified listener from the map such that it will no longer receive change notifications.

Specified by:

removeListener in interface EventuallyConsistentMap<K,V>

Parameters:

listener - listener to deregister for events

destroy

public void destroy()

Description copied from interface: EventuallyConsistentMap

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.

Specified by:

destroy in interface EventuallyConsistentMap<K,V>