Package org.onosproject.store.service
Interface AsyncConsistentMultimap<K,V>
-
- All Superinterfaces:
AsyncIterable<Map.Entry<K,V>>
,DistributedPrimitive
public interface AsyncConsistentMultimap<K,V> extends DistributedPrimitive, AsyncIterable<Map.Entry<K,V>>
Interface for a distributed multimap. NOTE: Editing any returned collection will NOT effect the map itself and changes in the map will NOT be reflected in the returned collections. Certain operations may be too expensive when backed by a distributed data structure and have been labeled as such.
-
-
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 default CompletableFuture<Void>
addListener(MultimapEventListener<K,V> listener)
Registers the specified listener to be notified whenever the map is updated.CompletableFuture<Void>
addListener(MultimapEventListener<K,V> listener, Executor executor)
Registers the specified listener to be notified whenever the map is updated.CompletableFuture<Map<K,Collection<V>>>
asMap()
Returns a map of keys to collections of values that reflect the set of key-value pairs contained in the multimap, where the key value pairs would be the key paired with each of the values in the collection.default ConsistentMultimap<K,V>
asMultimap()
Returns aConsistentMultimap
instance that wraps this map.default ConsistentMultimap<K,V>
asMultimap(long timeoutMillis)
Returns aConsistentMultimap
instance that wraps this map.CompletableFuture<Void>
clear()
Removes all key-value pairs, after which it will be empty.CompletableFuture<Boolean>
containsEntry(K key, V value)
Returns true if this map contains at least one key-value pair with key and value specified.CompletableFuture<Boolean>
containsKey(K key)
Returns true if there is at lease one key-value pair with a key equal to key.CompletableFuture<Boolean>
containsValue(V value)
Returns true if this map contains at lease one key-value pair with a value equal to value.default CompletableFuture<Void>
destroy()
Purges state associated with this primitive.CompletableFuture<Collection<Map.Entry<K,V>>>
entries()
Returns a collection of each key-value pair in this map.CompletableFuture<Versioned<Collection<? extends V>>>
get(K key)
Returns a collection of values associated with the specified key, if the key is not in the map it will return an empty collection.CompletableFuture<Boolean>
isEmpty()
Returns if this multimap contains no key-value pairs.CompletableFuture<com.google.common.collect.Multiset<K>>
keys()
Returns a multiset of the keys present in this multimap with one or more associated values each.CompletableFuture<Set<K>>
keySet()
Returns a set of the keys contained in this multimap with one or more associated values.default DistributedPrimitive.Type
primitiveType()
Returns the type of primitive.CompletableFuture<Boolean>
put(K key, V value)
If the key-value pair does not already exist adds either the key value pair or the value to the set of values associated with the key and returns true, if the key-value pair already exists then behavior is implementation specific with some implementations allowing duplicates and others ignoring put requests for existing entries.CompletableFuture<Boolean>
putAll(K key, Collection<? extends V> values)
Adds the set of key-value pairs of the specified key with each of the values in the iterable if each key-value pair does not already exist, if the pair does exist the behavior is implementation specific.CompletableFuture<Versioned<Collection<? extends V>>>
putAndGet(K key, V value)
If the key-value pair does not already exist adds either the key value pair or the value to the set of values associated with the key and returns the updated value, if the key-value pair already exists then behavior is implementation specific with some implementations allowing duplicates and others ignoring put requests for existing entries.CompletableFuture<Boolean>
remove(K key, V value)
Removes the key-value pair with the specified values if it exists.CompletableFuture<Versioned<Collection<? extends V>>>
removeAll(K key)
Removes all values associated with the specified key as well as the key itself.CompletableFuture<Boolean>
removeAll(K key, Collection<? extends V> values)
Removes the key-value pairs with the specified key and values if they exist.CompletableFuture<Versioned<Collection<? extends V>>>
removeAndGet(K key, V value)
Removes the key-value pair with the specified values if it exists.CompletableFuture<Void>
removeListener(MultimapEventListener<K,V> listener)
Unregisters the specified listener such that it will no longer receive map change notifications.CompletableFuture<Versioned<Collection<? extends V>>>
replaceValues(K key, Collection<V> values)
Stores all the values in values associated with the key specified, removes all preexisting values and returns a collection of the removed values which may be empty if the entry did not exist.CompletableFuture<Integer>
size()
Returns the number of key-value pairs in this multimap.CompletableFuture<com.google.common.collect.Multiset<V>>
values()
Returns a collection of values in the set with duplicates permitted, the size of this collection will equal the size of the map at the time of creation.-
Methods inherited from interface org.onosproject.store.service.AsyncIterable
iterator
-
Methods inherited from interface org.onosproject.store.service.DistributedPrimitive
addStatusChangeListener, applicationId, 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
-
destroy
default CompletableFuture<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 interfaceDistributedPrimitive
- Returns:
CompletableFuture
that is completed when the operation completes
-
size
CompletableFuture<Integer> size()
Returns the number of key-value pairs in this multimap.- Returns:
- the number of key-value pairs
-
isEmpty
CompletableFuture<Boolean> isEmpty()
Returns if this multimap contains no key-value pairs.- Returns:
- completable future that will be true if no key-value pairs exist, false otherwise
-
containsKey
CompletableFuture<Boolean> containsKey(K key)
Returns true if there is at lease one key-value pair with a key equal to key.- Parameters:
key
- the key to query- Returns:
- a future whose value will be true if the map contains a key-value pair with key false otherwise
-
containsValue
CompletableFuture<Boolean> containsValue(V value)
Returns true if this map contains at lease one key-value pair with a value equal to value.- Parameters:
value
- the value to query- Returns:
- a future whose value will be true if there is a key-value pair with the specified value, false otherwise.
-
containsEntry
CompletableFuture<Boolean> containsEntry(K key, V value)
Returns true if this map contains at least one key-value pair with key and value specified.- Parameters:
key
- keyvalue
- value- Returns:
- a future whose value will be true if there is a key-value pair with the specified key and value, false otherwise.
-
put
CompletableFuture<Boolean> put(K key, V value)
If the key-value pair does not already exist adds either the key value pair or the value to the set of values associated with the key and returns true, if the key-value pair already exists then behavior is implementation specific with some implementations allowing duplicates and others ignoring put requests for existing entries.- Parameters:
key
- the key to addvalue
- the value to add- Returns:
- a future whose value will be true if the map has changed because of this call, false otherwise
-
putAndGet
CompletableFuture<Versioned<Collection<? extends V>>> putAndGet(K key, V value)
If the key-value pair does not already exist adds either the key value pair or the value to the set of values associated with the key and returns the updated value, if the key-value pair already exists then behavior is implementation specific with some implementations allowing duplicates and others ignoring put requests for existing entries.- Parameters:
key
- the key to addvalue
- the value to add- Returns:
- a future to be completed with the updated values
-
remove
CompletableFuture<Boolean> remove(K key, V value)
Removes the key-value pair with the specified values if it exists. In implementations that allow duplicates which matching entry will be removed is undefined.- Parameters:
key
- the key of the pair to be removedvalue
- the value of the pair to be removed- Returns:
- a future whose value will be true if the map changed because of this call, false otherwise.
-
removeAndGet
CompletableFuture<Versioned<Collection<? extends V>>> removeAndGet(K key, V value)
Removes the key-value pair with the specified values if it exists. In implementations that allow duplicates which matching entry will be removed is undefined.- Parameters:
key
- the key of the pair to be removedvalue
- the value of the pair to be removed- Returns:
- a future to be completed with the updated values
-
removeAll
CompletableFuture<Boolean> removeAll(K key, Collection<? extends V> values)
Removes the key-value pairs with the specified key and values if they exist. In implementations that allow duplicates each instance of a key will remove one matching entry, which one is not defined. Equivalent to repeated calls toremove()
for each key value pair but more efficient.- Parameters:
key
- the key of the pair to be removedvalues
- the set of values to be removed- Returns:
- a future whose value will be true if the map changes because of this call, false otherwise.
-
removeAll
CompletableFuture<Versioned<Collection<? extends V>>> removeAll(K key)
Removes all values associated with the specified key as well as the key itself.- Parameters:
key
- the key whose key-value pairs will be removed- Returns:
- a future whose value is the set of values that were removed, which may be empty, if the values did not exist the version will be less than one.
-
putAll
CompletableFuture<Boolean> putAll(K key, Collection<? extends V> values)
Adds the set of key-value pairs of the specified key with each of the values in the iterable if each key-value pair does not already exist, if the pair does exist the behavior is implementation specific. (Same as repeated puts but with efficiency gains.)- Parameters:
key
- the key to use for all pairs to be addedvalues
- the set of values to be added in pairs with the key- Returns:
- a future whose value will be true if any change in the map results from this call, false otherwise
-
replaceValues
CompletableFuture<Versioned<Collection<? extends V>>> replaceValues(K key, Collection<V> values)
Stores all the values in values associated with the key specified, removes all preexisting values and returns a collection of the removed values which may be empty if the entry did not exist.- Parameters:
key
- the key for all entries to be addedvalues
- the values to be associated with the key- Returns:
- a future whose value will be the collection of removed values, which may be empty
-
clear
CompletableFuture<Void> clear()
Removes all key-value pairs, after which it will be empty.- Returns:
- a future whose value is irrelevant, simply used to determine if the call has completed
-
get
CompletableFuture<Versioned<Collection<? extends V>>> get(K key)
Returns a collection of values associated with the specified key, if the key is not in the map it will return an empty collection.- Parameters:
key
- the key whose associated values will be returned- Returns:
- a future whose value will be the collection of the values associated with the specified key, the collection may be empty
-
keySet
CompletableFuture<Set<K>> keySet()
Returns a set of the keys contained in this multimap with one or more associated values.- Returns:
- a future whose value will be the collection of all keys with one or more associated values, this may be empty
-
keys
CompletableFuture<com.google.common.collect.Multiset<K>> keys()
Returns a multiset of the keys present in this multimap with one or more associated values each. Keys will appear once for each key-value pair in which they participate.- Returns:
- a future whose value will be a multiset of the keys, this may be empty
-
values
CompletableFuture<com.google.common.collect.Multiset<V>> values()
Returns a collection of values in the set with duplicates permitted, the size of this collection will equal the size of the map at the time of creation.- Returns:
- a future whose value will be a collection of values, this may be empty
-
entries
CompletableFuture<Collection<Map.Entry<K,V>>> entries()
Returns a collection of each key-value pair in this map.- Returns:
- a future whose value will be a collection of all entries in the map, this may be empty
-
addListener
default CompletableFuture<Void> addListener(MultimapEventListener<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
CompletableFuture<Void> addListener(MultimapEventListener<K,V> listener, Executor executor)
Registers the specified listener to be notified whenever the map is updated.- Parameters:
listener
- listener to notify about map eventsexecutor
- executor to use for handling incoming map events- Returns:
- future that will be completed when the operation finishes
-
removeListener
CompletableFuture<Void> removeListener(MultimapEventListener<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
-
asMap
CompletableFuture<Map<K,Collection<V>>> asMap()
Returns a map of keys to collections of values that reflect the set of key-value pairs contained in the multimap, where the key value pairs would be the key paired with each of the values in the collection.- Returns:
- a future whose value will be a map of keys to collections of values, the returned map may be empty.
-
asMultimap
default ConsistentMultimap<K,V> asMultimap()
Returns aConsistentMultimap
instance that wraps this map. All calls will have the same behavior as this map but will be blocking instead of asynchronous. If a call does not complete within the default timeout an exception will be produced.- Returns:
- a
ConsistentMultimap
which wraps this map, providing synchronous access to this map
-
asMultimap
default ConsistentMultimap<K,V> asMultimap(long timeoutMillis)
Returns aConsistentMultimap
instance that wraps this map. All calls will have the same behavior as this map but will be blocking instead of asynchronous. If a call does not complete within the specified timeout an exception will be produced.- Parameters:
timeoutMillis
- the number of millis to block while waiting for a call to return- Returns:
- a
ConsistentMultimap
which wraps this map, providing synchronous access to this map
-
-