org.onosproject.store.service

Interface AsyncConsistentMap<K,V>

All Superinterfaces:

DistributedPrimitive, Transactional<MapUpdate<K,V>>

All Known Subinterfaces:

AsyncConsistentTreeMap<V>

public interface AsyncConsistentMap<K,V>
extends DistributedPrimitive, Transactional<MapUpdate<K,V>>

A distributed, strongly consistent map whose methods are all executed asynchronously.

This map offers strong read-after-update (where update == create/update/delete) consistency. All operations to the map are serialized and applied in a consistent manner.

The stronger consistency comes at the expense of availability in the event of a network partition. A network partition can be either due to a temporary disruption in network connectivity between participating nodes or due to a node being temporarily down.

All values stored in this map are versioned and the API supports optimistic concurrency by allowing conditional updates that take into consideration the version or value that was previously read.

This map does not allow null values. All methods can throw a ConsistentMapException (which extends RuntimeException) to indicate failures.

All methods of this interface return a future immediately after a successful invocation. The operation itself is executed asynchronous and the returned future will be completed when the operation finishes.

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
default java.util.concurrent.CompletableFuture<java.lang.Void>	addListener(MapEventListener<K,V> listener) Registers the specified listener to be notified whenever the map is updated.
java.util.concurrent.CompletableFuture<java.lang.Void>	addListener(MapEventListener<K,V> listener, java.util.concurrent.Executor executor) Registers the specified listener to be notified whenever the map is updated.
default ConsistentMap<K,V>	asConsistentMap() Returns a new ConsistentMap that is backed by this instance.
default ConsistentMap<K,V>	asConsistentMap(long timeoutMillis) Returns a new ConsistentMap that is backed by this instance.
java.util.concurrent.CompletableFuture<java.lang.Void>	clear() Removes all of the mappings from this map (optional operation).
default java.util.concurrent.CompletableFuture<Versioned<V>>	compute(K key, java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction) Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
java.util.concurrent.CompletableFuture<Versioned<V>>	computeIf(K key, java.util.function.Predicate<? super V> condition, java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction) If the value for the specified key satisfies a condition, attempts to compute a new mapping given the key and its current mapped value.
default java.util.concurrent.CompletableFuture<Versioned<V>>	computeIfAbsent(K key, java.util.function.Function<? super K,? extends V> mappingFunction) If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null.
default java.util.concurrent.CompletableFuture<Versioned<V>>	computeIfPresent(K key, java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction) If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	containsKey(K key) Returns true if this map contains a mapping for the specified key.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	containsValue(V value) Returns true if this map contains the specified value.
default java.util.concurrent.CompletableFuture<java.lang.Void>	destroy() Purges state associated with this primitive.
java.util.concurrent.CompletableFuture<java.util.Set<java.util.Map.Entry<K,Versioned<V>>>>	entrySet() Returns the set of entries contained in this map.
java.util.concurrent.CompletableFuture<Versioned<V>>	get(K key) Returns the value (and version) to which the specified key is mapped, or null if this map contains no mapping for the key.
java.util.concurrent.CompletableFuture<Versioned<V>>	getOrDefault(K key, V defaultValue) Returns the value (and version) to which the specified key is mapped, or the provided default value if this map contains no mapping for the key.
default java.util.concurrent.CompletableFuture<java.lang.Boolean>	isEmpty() Returns true if the map is empty.
java.util.concurrent.CompletableFuture<java.util.Set<K>>	keySet() Returns a Set view of the keys contained in this map.
default DistributedPrimitive.Type	primitiveType() Returns the type of primitive.
java.util.concurrent.CompletableFuture<Versioned<V>>	put(K key, V value) Associates the specified value with the specified key in this map (optional operation).
java.util.concurrent.CompletableFuture<Versioned<V>>	putAndGet(K key, V value) Associates the specified value with the specified key in this map (optional operation).
java.util.concurrent.CompletableFuture<Versioned<V>>	putIfAbsent(K key, V value) If the specified key is not already associated with a value associates it with the given value and returns null, else behaves as a get returning the existing mapping without making any changes.
java.util.concurrent.CompletableFuture<Versioned<V>>	remove(K key) Removes the mapping for a key from this map if it is present (optional operation).
java.util.concurrent.CompletableFuture<java.lang.Boolean>	remove(K key, long version) Removes the entry for the specified key only if its current version in the map is equal to the specified version.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	remove(K key, V value) Removes the entry for the specified key only if it is currently mapped to the specified value.
java.util.concurrent.CompletableFuture<java.lang.Void>	removeListener(MapEventListener<K,V> listener) Unregisters the specified listener such that it will no longer receive map change notifications.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	replace(K key, long oldVersion, V newValue) Replaces the entry for the specified key only if it is currently mapped to the specified version.
java.util.concurrent.CompletableFuture<Versioned<V>>	replace(K key, V value) Replaces the entry for the specified key only if there is any value which associated with specified key.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	replace(K key, V oldValue, V newValue) Replaces the entry for the specified key only if currently mapped to the specified value.
java.util.concurrent.CompletableFuture<java.lang.Integer>	size() Returns the number of entries in the map.
java.util.concurrent.CompletableFuture<java.util.Collection<Versioned<V>>>	values() Returns the collection of values (and associated versions) contained in this map.

Methods inherited from interface org.onosproject.store.service.DistributedPrimitive

addStatusChangeListener, applicationId, name, removeStatusChangeListener, statusChangeListeners

Methods inherited from interface org.onosproject.store.service.Transactional

begin, commit, prepare, prepareAndCommit, rollback

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

destroy

default java.util.concurrent.CompletableFuture<java.lang.Void> destroy()

Description copied from interface: DistributedPrimitive

Purges state associated with this primitive.

Implementations can override and provide appropriate clean up logic for purging any state state associated with the primitive. Whether modifications made within the destroy method have local or global visibility is left unspecified.

Specified by:

destroy in interface DistributedPrimitive

Returns:

CompletableFuture that is completed when the operation completes

size

java.util.concurrent.CompletableFuture<java.lang.Integer> size()

Returns the number of entries in the map.

Returns:

a future for map size.

isEmpty

default java.util.concurrent.CompletableFuture<java.lang.Boolean> isEmpty()

Returns true if the map is empty.

Returns:

a future whose value will be true if map has no entries, false otherwise.

containsKey

java.util.concurrent.CompletableFuture<java.lang.Boolean> containsKey(K key)

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

Parameters:

key - key

Returns:

a future whose value will be true if map contains key, false otherwise.

containsValue

java.util.concurrent.CompletableFuture<java.lang.Boolean> containsValue(V value)

Returns true if this map contains the specified value.

Parameters:

value - value

Returns:

a future whose value will be true if map contains value, false otherwise.

get

java.util.concurrent.CompletableFuture<Versioned<V>> get(K key)

Returns the value (and version) to which the specified key is mapped, or null if this map contains no mapping for the key.

Parameters:

key - the key whose associated value (and version) is to be returned

Returns:

a future value (and version) to which the specified key is mapped, or null if this map contains no mapping for the key

getOrDefault

java.util.concurrent.CompletableFuture<Versioned<V>> getOrDefault(K key,
                                                                  V defaultValue)

Returns the value (and version) to which the specified key is mapped, or the provided default value if this map contains no mapping for the key.

Parameters:

key - the key whose associated value (and version) is to be returned

defaultValue - the default value to return if the key is not set

Returns:

a future value (and version) to which the specified key is mapped, or null if this map contains no mapping for the key

computeIfAbsent

default java.util.concurrent.CompletableFuture<Versioned<V>> computeIfAbsent(K key,
                                                                             java.util.function.Function<? super K,? extends V> mappingFunction)

If the specified key is not already associated with a value (or is mapped to null), attempts to compute its value using the given mapping function and enters it into this map unless null. If a conflicting concurrent modification attempt is detected, the returned future will be completed exceptionally with ConsistentMapException.ConcurrentModification.

Parameters:

key - key with which the specified value is to be associated

mappingFunction - the function to compute a value

Returns:

the current (existing or computed) value associated with the specified key, or null if the computed value is null

computeIfPresent

default java.util.concurrent.CompletableFuture<Versioned<V>> computeIfPresent(K key,
                                                                              java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction)

If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value. If the computed value is null, the current mapping will be removed from the map. If a conflicting concurrent modification attempt is detected, the returned future will be completed exceptionally with ConsistentMapException.ConcurrentModification.

Parameters:

key - key with which the specified value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if computed value is null

compute

default java.util.concurrent.CompletableFuture<Versioned<V>> compute(K key,
                                                                     java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction)

Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping). If the computed value is null, the current mapping (if one exists) will be removed from the map. If a conflicting concurrent modification attempt is detected, the returned future will be completed exceptionally with ConsistentMapException.ConcurrentModification.

Parameters:

key - key with which the specified value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if computed value is null

computeIf

java.util.concurrent.CompletableFuture<Versioned<V>> computeIf(K key,
                                                               java.util.function.Predicate<? super V> condition,
                                                               java.util.function.BiFunction<? super K,? super V,? extends V> remappingFunction)

If the value for the specified key satisfies a condition, attempts to compute a new mapping given the key and its current mapped value. If the computed value is null, the current mapping will be removed from the map. If a conflicting concurrent modification attempt is detected, the returned future will be completed exceptionally with ConsistentMapException.ConcurrentModification.

Parameters:

key - key with which the specified value is to be associated

condition - condition that should evaluate to true for the computation to proceed

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or the old value if condition evaluates to false

put

java.util.concurrent.CompletableFuture<Versioned<V>> put(K key,
                                                         V value)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value.

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 (and version) associated with key, or null if there was no mapping for key.

putAndGet

java.util.concurrent.CompletableFuture<Versioned<V>> putAndGet(K key,
                                                               V value)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

new value.

remove

java.util.concurrent.CompletableFuture<Versioned<V>> remove(K key)

Removes the mapping for a key from this map if it is present (optional operation).

Parameters:

key - key whose value is to be removed from the map

Returns:

the value (and version) to which this map previously associated the key, or null if the map contained no mapping for the key.

clear

java.util.concurrent.CompletableFuture<java.lang.Void> clear()

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Returns:

future that will be successfully completed when the map is cleared

keySet

java.util.concurrent.CompletableFuture<java.util.Set<K>> keySet()

Returns a Set view of the keys contained in this map. This method differs from the behavior of java.util.Map.keySet() in that what is returned is a unmodifiable snapshot view of the keys in the ConsistentMap. Attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException.

Returns:

a set of the keys contained in this map

values

java.util.concurrent.CompletableFuture<java.util.Collection<Versioned<V>>> values()

Returns the collection of values (and associated versions) contained in this map. This method differs from the behavior of java.util.Map.values() in that what is returned is a unmodifiable snapshot view of the values in the ConsistentMap. Attempts to modify the returned collection, whether direct or via its iterator, result in an UnsupportedOperationException.

Returns:

a collection of the values (and associated versions) contained in this map

entrySet

java.util.concurrent.CompletableFuture<java.util.Set<java.util.Map.Entry<K,Versioned<V>>>> entrySet()

Returns the set of entries contained in this map. This method differs from the behavior of java.util.Map.entrySet() in that what is returned is a unmodifiable snapshot view of the entries in the ConsistentMap. Attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException.

Returns:

set of entries contained in this map.

putIfAbsent

java.util.concurrent.CompletableFuture<Versioned<V>> putIfAbsent(K key,
                                                                 V value)

If the specified key is not already associated with a value associates it with the given value and returns null, else behaves as a get returning the existing mapping without making any changes.

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 the specified key or null if key does not already mapped to a value.

remove

java.util.concurrent.CompletableFuture<java.lang.Boolean> remove(K key,
                                                                 V value)

Removes the entry for the specified key only if it is currently mapped to the specified value.

Parameters:

key - key with which the specified value is associated

value - value expected to be associated with the specified key

Returns:

true if the value was removed

remove

java.util.concurrent.CompletableFuture<java.lang.Boolean> remove(K key,
                                                                 long version)

Removes the entry for the specified key only if its current version in the map is equal to the specified version.

Parameters:

key - key with which the specified version is associated

version - version expected to be associated with the specified key

Returns:

true if the value was removed

replace

java.util.concurrent.CompletableFuture<Versioned<V>> replace(K key,
                                                             V value)

Replaces the entry for the specified key only if there is any value which associated with specified key.

Parameters:

key - key with which the specified value is associated

value - value expected to be associated with the specified key

Returns:

the previous value associated with the specified key or null

replace

java.util.concurrent.CompletableFuture<java.lang.Boolean> replace(K key,
                                                                  V oldValue,
                                                                  V newValue)

Replaces the entry for the specified key only if currently mapped to the specified value.

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

newValue - value to be associated with the specified key

Returns:

true if the value was replaced

replace

java.util.concurrent.CompletableFuture<java.lang.Boolean> replace(K key,
                                                                  long oldVersion,
                                                                  V newValue)

Replaces the entry for the specified key only if it is currently mapped to the specified version.

Parameters:

key - key key with which the specified value is associated

oldVersion - version expected to be associated with the specified key

newValue - value to be associated with the specified key

Returns:

true if the value was replaced

addListener

default java.util.concurrent.CompletableFuture<java.lang.Void> addListener(MapEventListener<K,V> listener)

Registers the specified listener to be notified whenever the map is updated.

Parameters:

listener - listener to notify about map events

Returns:

future that will be completed when the operation finishes

addListener

java.util.concurrent.CompletableFuture<java.lang.Void> addListener(MapEventListener<K,V> listener,
                                                                   java.util.concurrent.Executor executor)

Registers the specified listener to be notified whenever the map is updated.

Parameters:

listener - listener to notify about map events

executor - executor to use for handling incoming map events

Returns:

future that will be completed when the operation finishes

removeListener

java.util.concurrent.CompletableFuture<java.lang.Void> removeListener(MapEventListener<K,V> listener)

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

Parameters:

listener - listener to unregister

Returns:

future that will be completed when the operation finishes

asConsistentMap

default ConsistentMap<K,V> asConsistentMap()

Returns a new ConsistentMap that is backed by this instance.

Returns:

new ConsistentMap instance

asConsistentMap

default ConsistentMap<K,V> asConsistentMap(long timeoutMillis)

Returns a new ConsistentMap that is backed by this instance.

Parameters:

timeoutMillis - timeout duration for the returned ConsistentMap operations

Returns:

new ConsistentMap instance