io.atomix.collections

Class DistributedMap<K,V>

java.lang.Object

io.atomix.resource.AbstractResource<DistributedMap<K,V>>

io.atomix.collections.DistributedMap<K,V>

Type Parameters:

K - The map key type.

V - The map entry type.

All Implemented Interfaces:

Managed<DistributedMap<K,V>>, io.atomix.resource.Resource<DistributedMap<K,V>>

public class DistributedMap<K,V>
extends io.atomix.resource.AbstractResource<DistributedMap<K,V>>

Stores a map of keys to values.

The distributed map stores a map of keys and values via an interface similar to that of Map. Map entries are stored in memory on each stateful node and backed by disk, thus the size of the map is limited to the available memory on the smallest node in the cluster. This map requires non-null keys but supports null values. All keys and values must be serializable by a Serializer. Serializable types include implementations of Serializable or CatalystSerializable. See the serialization API for more information.

A DistributedMap can be created either via the Atomix API or by wrapping a CopycatClient directly. To create a map via the Atomix API, use the getMap factory method:

   
   DistributedMap<String, String> map = atomix.getMap("foo").get();
   
 

Maps are distributed and are referenced by the map name. If a value is put(Object, Object) in a map on one node, that value is immediately available for reading by any other node in the cluster by operating on the same map.

In addition to supporting normal Map methods, this implementation supports values with TTLs. When a key is set with a TTL, the value will expire and be automatically evicted from the map some time after the TTL.

Author:

Jordan Halterman

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DistributedMap.EntryEvent<K,V> Map entry event.
static class	DistributedMap.Events Distributed queue events.
static class	DistributedMap.Options Distributed map options.

Nested classes/interfaces inherited from interface io.atomix.resource.Resource

io.atomix.resource.Resource.Config, io.atomix.resource.Resource.Event, io.atomix.resource.Resource.EventType, io.atomix.resource.Resource.State

Constructor Summary

Constructors

Constructor and Description
DistributedMap(CopycatClient client)
DistributedMap(CopycatClient client, Properties options)

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	clear() Removes all entries from the map.
CompletableFuture<Boolean>	containsKey(Object key) Returns true if the given key is present in the map.
CompletableFuture<Boolean>	containsKey(Object key, io.atomix.resource.ReadConsistency consistency) Returns true if the given key is present in the map.
CompletableFuture<Boolean>	containsValue(Object value) Returns true if the map contains a key with the given value.
CompletableFuture<Boolean>	containsValue(Object value, io.atomix.resource.ReadConsistency consistency) Returns true if the map contains a key with the given value.
CompletableFuture<Set<Map.Entry<K,V>>>	entrySet() Reads the set of all entries in the map.
CompletableFuture<Set<Map.Entry<K,V>>>	entrySet(io.atomix.resource.ReadConsistency consistency) Reads the set of all entries in the map.
CompletableFuture<V>	get(Object key) Gets a value from the map.
CompletableFuture<V>	get(Object key, io.atomix.resource.ReadConsistency consistency) Gets a value from the map.
CompletableFuture<V>	getOrDefault(Object key, V defaultValue) Gets the value of key or returns the given default value if key does not exist.
CompletableFuture<V>	getOrDefault(Object key, V defaultValue, io.atomix.resource.ReadConsistency consistency) Gets the value of key or returns the given default value if key does not exist.
CompletableFuture<Boolean>	isEmpty() Returns true if the map is empty.
CompletableFuture<Boolean>	isEmpty(io.atomix.resource.ReadConsistency consistency) Returns true if the map is empty.
CompletableFuture<Set<K>>	keySet() Reads the set of all keys in the map.
CompletableFuture<Set<K>>	keySet(io.atomix.resource.ReadConsistency consistency) Reads the set of all keys in the map.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onAdd(Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a put(Object, Object) event listener.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onAdd(K key, Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a put(Object, Object) event listener.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onRemove(Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a remove(Object) event listener.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onRemove(K key, Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a remove(Object) event listener.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onUpdate(Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a put(Object, Object) event listener.
CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>>	onUpdate(K key, Consumer<DistributedMap.EntryEvent<K,V>> callback) Registers a put(Object, Object) event listener.
CompletableFuture<DistributedMap<K,V>>	open()
DistributedMap.Options	options()
CompletableFuture<V>	put(K key, V value) Puts a value in the map for the given key.
CompletableFuture<V>	put(K key, V value, Duration ttl) Puts a value in the map with a time-to-live for the given key.
CompletableFuture<V>	putIfAbsent(K key, V value) Puts a value in the map if the given key does not exist.
CompletableFuture<V>	putIfAbsent(K key, V value, Duration ttl) Puts a value with a time-to-live in the map if the given key does not exist.
CompletableFuture<Boolean>	remove(K key, V value) Removes the given key from the map if its value matches the given value.
CompletableFuture<V>	remove(Object key) Removes a the value for the given key from the map.
CompletableFuture<V>	replace(K key, V value) Replaces a value in the map if the key exists.
CompletableFuture<V>	replace(K key, V value, Duration ttl) Replaces a value in the map if the key exist.
CompletableFuture<Boolean>	replace(K key, V oldValue, V newValue) Replaces a value in the map.
CompletableFuture<Boolean>	replace(K key, V oldValue, V newValue, Duration ttl) Replaces a value in the map with a time-to-live.
CompletableFuture<Integer>	size() Gets the number of key-value pairs in the map.
CompletableFuture<Integer>	size(io.atomix.resource.ReadConsistency consistency) Gets the number of key-value pairs in the map.
CompletableFuture<Collection<V>>	values() Reads the collection of all values in the map.
CompletableFuture<Collection<V>>	values(io.atomix.resource.ReadConsistency consistency) Reads the collection of all values in the map.

Methods inherited from class io.atomix.resource.AbstractResource

close, config, context, delete, equals, hashCode, isClosed, isOpen, onRecovery, onStateChange, serializer, state, toString, type

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DistributedMap

public DistributedMap(CopycatClient client)

DistributedMap

public DistributedMap(CopycatClient client,
                      Properties options)

Method Detail

options

public DistributedMap.Options options()

Specified by:

options in interface io.atomix.resource.Resource<DistributedMap<K,V>>

Overrides:

options in class io.atomix.resource.AbstractResource<DistributedMap<K,V>>

isEmpty

public CompletableFuture<Boolean> isEmpty()

Returns true if the map is empty.

Note that depending on the configured ReadConsistency of the map instance, empty checks may return stale results. To perform a fully consistent empty check, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).isEmpty().thenAccept(isEmpty -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.isEmpty().get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.isEmpty().thenAccept(isEmpty -> {
     ...
   });
   
 

Returns:

A completable future to be completed with a boolean value indicating whether the map is empty.

isEmpty

public CompletableFuture<Boolean> isEmpty(io.atomix.resource.ReadConsistency consistency)

Returns true if the map is empty.

Note that depending on the ReadConsistency, empty checks may return stale results. To perform a fully consistent empty check, use ReadConsistency.ATOMIC consistency (the default).

   
   map.isEmpty(ReadConsistency.ATOMIC).thenAccept(isEmpty -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.isEmpty(ReadConsistency.ATOMIC).get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.isEmpty(ReadConsistency.ATOMIC).thenAccept(isEmpty -> {
     ...
   });
   
 

Parameters:

consistency - The read consistency level.

Returns:

A completable future to be completed with a boolean value indicating whether the map is empty.

size

public CompletableFuture<Integer> size()

Gets the number of key-value pairs in the map.

Note that depending on the configured ReadConsistency of the map instance, size checks may return stale results. To perform a fully consistent size check, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).size().thenAccept(size -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   int size = map.size().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.size().thenAccept(size -> {
     ...
   });
   
 

Returns:

A completable future to be completed with the number of entries in the map.

size

public CompletableFuture<Integer> size(io.atomix.resource.ReadConsistency consistency)

Gets the number of key-value pairs in the map.

Note that depending on the ReadConsistency, size checks may return stale results. To perform a fully consistent size check, use ReadConsistency.ATOMIC consistency (the default).

   
   map.size(ReadConsistency.ATOMIC).thenAccept(size -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   int size = map.size(ReadConsistency.ATOMIC).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.size(ReadConsistency.ATOMIC).thenAccept(size -> {
     ...
   });
   
 

Parameters:

consistency - The read consistency level.

Returns:

A completable future to be completed with the number of entries in the map.

containsKey

public CompletableFuture<Boolean> containsKey(Object key)

Returns true if the given key is present in the map.

Note that depending on the configured ReadConsistency of the map instance, checks may return stale results. To perform a fully consistent check, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).containsKey("foo").thenAccept(contains -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.containsKey("foo").get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.containsKey("foo").thenAccept(contains -> {
     ...
   });
   
 

Parameters:

key - The key to check.

Returns:

A completable future to be completed with a boolean indicating whether key is present in the map.

Throws:

NullPointerException - if key is null

containsKey

public CompletableFuture<Boolean> containsKey(Object key,
                                              io.atomix.resource.ReadConsistency consistency)

Returns true if the given key is present in the map.

Note that depending on the ReadConsistency, checks may return stale results. To perform a fully consistent check, use ReadConsistency.ATOMIC consistency (the default).

   
   map.containsKey("foo", ReadConsistency.ATOMIC).thenAccept(contains -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.containsKey("foo", ReadConsistency.ATOMIC).get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.containsKey("foo", ReadConsistency.ATOMIC).thenAccept(contains -> {
     ...
   });
   
 

Parameters:

key - The key to check.

consistency - The read consistency level.

Returns:

A completable future to be completed with a boolean indicating whether key is present in the map.

Throws:

NullPointerException - if key is null

containsValue

public CompletableFuture<Boolean> containsValue(Object value)

Returns true if the map contains a key with the given value.

Note that depending on the configured ReadConsistency of the map instance, checks may return stale results. To perform a fully consistent check, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).containsValue("foo").thenAccept(contains -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.containsValue("foo").get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.containsValue("foo").thenAccept(contains -> {
     ...
   });
   
 

Parameters:

value - The value for which to search keys.

Returns:

A completable future to be completed with a boolean indicating whether key is present in the map.

Throws:

NullPointerException - if key is null

containsValue

public CompletableFuture<Boolean> containsValue(Object value,
                                                io.atomix.resource.ReadConsistency consistency)

Returns true if the map contains a key with the given value.

Note that depending on the ReadConsistency, checks may return stale results. To perform a fully consistent check, use ReadConsistency.ATOMIC consistency (the default).

   
   map.containsValue("foo", ReadConsistency.ATOMIC).thenAccept(contains -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (map.containsValue("foo", ReadConsistency.ATOMIC).get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.containsValue("foo", ReadConsistency.ATOMIC).thenAccept(contains -> {
     ...
   });
   
 

Parameters:

value - The value for which to search keys.

consistency - The read consistency level.

Returns:

A completable future to be completed with a boolean indicating whether key is present in the map.

Throws:

NullPointerException - if key is null

get

public CompletableFuture<V> get(Object key)

Gets a value from the map.

Note that depending on the configured ReadConsistency of the map instance, queries may return stale results. To perform a fully consistent query, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).get("key").thenAccept(value -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   String value = map.get("key").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.get("key").thenAccept(value -> {
     ...
   });
   
 

Parameters:

key - The key to get.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

get

public CompletableFuture<V> get(Object key,
                                io.atomix.resource.ReadConsistency consistency)

Gets a value from the map.

Note that depending on the ReadConsistency, queries may return stale results. To perform a fully consistent query, use ReadConsistency.ATOMIC consistency (the default).

   
   map.get("key", ReadConsistency.ATOMIC).thenAccept(value -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   String value = map.get("key", ReadConsistency.ATOMIC).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.get("key", ReadConsistency.ATOMIC).thenAccept(value -> {
     ...
   });
   
 

Parameters:

key - The key to get.

consistency - The read consistency level.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

getOrDefault

public CompletableFuture<V> getOrDefault(Object key,
                                         V defaultValue)

Gets the value of key or returns the given default value if key does not exist.

If no value for the given key is present in the map, the returned CompletableFuture will be completed null. If a value is present, the returned future will be completed with that value.

Note that depending on the configured ReadConsistency of the map instance, queries may return stale results. To perform a fully consistent query, configure the map with ReadConsistency.ATOMIC consistency (the default).

   
   map.with(Consistency.ATOMIC).getOrDefault("key", "Hello world!").thenAccept(value -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   String valueOrDefault = map.getOrDefault("key", "Hello world!").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.getOrDefault("key", "Hello world!").thenAccept(valueOrDefault -> {
     ...
   });
   
 

Parameters:

key - The key to get.

defaultValue - The default value to return if the key does not exist.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

getOrDefault

public CompletableFuture<V> getOrDefault(Object key,
                                         V defaultValue,
                                         io.atomix.resource.ReadConsistency consistency)

Gets the value of key or returns the given default value if key does not exist.

If no value for the given key is present in the map, the returned CompletableFuture will be completed null. If a value is present, the returned future will be completed with that value.

Note that depending on the ReadConsistency, queries may return stale results. To perform a fully consistent query, use ReadConsistency.ATOMIC consistency (the default).

   
   map.getOrDefault("key", "Hello world!", ReadConsistency.ATOMIC).thenAccept(value -> {
     ...
   });
   
 

For better performance with potentially stale results, use a lower consistency level. See the ReadConsistency documentation for specific consistency guarantees.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   String valueOrDefault = map.getOrDefault("key", "Hello world!", ReadConsistency.ATOMIC).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.getOrDefault("key", "Hello world!", ReadConsistency.ATOMIC).thenAccept(valueOrDefault -> {
     ...
   });
   
 

Parameters:

key - The key to get.

defaultValue - The default value to return if the key does not exist.

consistency - The read consistency level.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

put

public CompletableFuture<V> put(K key,
                                V value)

Puts a value in the map for the given key.

Any previous value associated with the given key will be overridden. Additionally, if the previous value was set with a TTL, the TTL will be cancelled and this value will be set with no TTL.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.put("key", "Hello world!").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.put("key", "Hello world!").thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to set.

value - The value to set.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

put

public CompletableFuture<V> put(K key,
                                V value,
                                Duration ttl)

Puts a value in the map with a time-to-live for the given key.

Any previous value associated with the given key will be overridden. Additionally, if the previous value was set with a TTL, the TTL will be cancelled and this value's TTL will be set.

The value will remain in the map until the provided Duration of time has elapsed or it is overridden by a more recent put operation. Note that the provided ttl should only be considered an estimate of time. Values may be evicted at some arbitrary point after the provided duration has elapsed, but never before.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.put("key", "Hello world!", Duration.ofSeconds(10)).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.put("key", "Hello world!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to set.

value - The value to set.

ttl - The duration after which to expire the key.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

putIfAbsent

public CompletableFuture<V> putIfAbsent(K key,
                                        V value)

Puts a value in the map if the given key does not exist.

If the given key is not already present in the map, the key will be set to the given value.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.put("key", "Hello world!").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.put("key", "Hello world!").thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to set.

value - The value to set if the given key does not exist.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

putIfAbsent

public CompletableFuture<V> putIfAbsent(K key,
                                        V value,
                                        Duration ttl)

Puts a value with a time-to-live in the map if the given key does not exist.

If the given key is not already present in the map, the key will be set to the given value.

The value will remain in the map until the provided Duration of time has elapsed or it is overridden by a more recent put operation. Note that the provided ttl should only be considered an estimate of time. Values may be evicted at some arbitrary point after the provided duration has elapsed, but never before.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.put("key", "Hello world!", Duration.ofSeconds(10)).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.put("key", "Hello world!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to set.

value - The value to set if the given key does not exist.

ttl - The time to live duration.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

remove

public CompletableFuture<V> remove(Object key)

Removes a the value for the given key from the map.

If no value for the given key is present in the map, the returned CompletableFuture will be completed null. If a value is present, that value will be removed from the distributed map and the returned future will be completed with that value. If the previous value was set with a TTL, the TTL will be cancelled.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.remove("key").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.remove("key").thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to remove.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

remove

public CompletableFuture<Boolean> remove(K key,
                                         V value)

Removes the given key from the map if its value matches the given value.

If no value for the given key is present in the map or if the value doesn't match the provided value, the returned CompletableFuture will be completed false. If a value is present and matches value, that value will be removed from the distributed map and the returned future will be completed true. If the previous value was set with a TTL, the TTL will be cancelled.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   if (map.remove("key", "Hello world!").get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.remove("key", "Hello world!").thenAccept(removed -> {
     ...
   });
   
 

Parameters:

key - The key to remove.

value - The value to remove.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

replace

public CompletableFuture<V> replace(K key,
                                    V value)

Replaces a value in the map if the key exists.

If the given key is not already present in the map, no change will be made and null will be returned.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.replace("key", "Hello world!").get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.replace("key", "Hello world!").thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to replace.

value - The value with which to replace the key if it exists.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

replace

public CompletableFuture<V> replace(K key,
                                    V value,
                                    Duration ttl)

Replaces a value in the map if the key exist.

If the given key is not already present in the map, no change will be made and null will be returned.

If the value is successfully replaced, the value will remain in the map until the provided Duration of time has elapsed or it is overridden by a more recent put operation. Note that the provided ttl should only be considered an estimate of time. Values may be evicted at some arbitrary point after the provided duration has elapsed, but never before.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   String oldValue = map.replace("key", "Hello world!", Duration.ofSeconds(10)).get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.replace("key", "Hello world!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to replace.

value - The value with which to replace the key if it exists.

ttl - The duration after which to expire the key/value.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

replace

public CompletableFuture<Boolean> replace(K key,
                                          V oldValue,
                                          V newValue)

Replaces a value in the map.

If the given key is not already present in the map, no change will be made and null will be returned. If the key is present and its value matches oldValue, it will be updated with newValue.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   if (map.replace("key", "Hello world!", "Hello world again!").get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.replace("key", "Hello world!", "Hello world again!").thenAccept(replaced -> {
     ...
   });
   
 

Parameters:

key - The key to replace.

oldValue - The value to check.

newValue - The value to replace.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

replace

public CompletableFuture<Boolean> replace(K key,
                                          V oldValue,
                                          V newValue,
                                          Duration ttl)

Replaces a value in the map with a time-to-live.

If the given key is not already present in the map, no change will be made and null will be returned. If the key is present and its value matches oldValue, it will be updated with newValue.

If the value is successfully replaced, the value will remain in the map until the provided Duration of time has elapsed or it is overridden by a more recent put operation. Note that the provided ttl should only be considered an estimate of time. Values may be evicted at some arbitrary point after the provided duration has elapsed, but never before.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   if (map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).get()) {
     ...
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Parameters:

key - The key to replace.

oldValue - The value to check.

newValue - The value to replace.

ttl - The duration after which to expire the key/value.

Returns:

A completable future to be completed with the result once complete.

Throws:

NullPointerException - if key is null

keySet

public CompletableFuture<Set<K>> keySet()

Reads the set of all keys in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Returns:

A completable future to be completed with the result once complete.

keySet

public CompletableFuture<Set<K>> keySet(io.atomix.resource.ReadConsistency consistency)

Reads the set of all keys in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

If the provided ReadConsistency is ReadConsistency.LOCAL and local caching is enabled for the map, reads will be serviced via the cache. Otherwise, reads will fall back to ReadConsistency.SEQUENTIAL if the cache is not enabled.

Parameters:

consistency - The read consistency level.

Returns:

A completable future to be completed with the result once complete.

values

public CompletableFuture<Collection<V>> values()

Reads the collection of all values in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Returns:

A completable future to be completed with the result once complete.

values

public CompletableFuture<Collection<V>> values(io.atomix.resource.ReadConsistency consistency)

Reads the collection of all values in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

If the provided ReadConsistency is ReadConsistency.LOCAL and local caching is enabled for the map, reads will be serviced via the cache. Otherwise, reads will fall back to ReadConsistency.SEQUENTIAL if the cache is not enabled.

Parameters:

consistency - The read consistency level.

Returns:

A completable future to be completed with the result once complete.

entrySet

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

Reads the set of all entries in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

Returns:

A completable future to be completed with the result once complete.

entrySet

public CompletableFuture<Set<Map.Entry<K,V>>> entrySet(io.atomix.resource.ReadConsistency consistency)

Reads the set of all entries in the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() or CompletableFuture.join() method to block the calling thread:

   
   Set<String> keys = map.keySet().get();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.keySet().thenAccept(keys -> {
     keys.forEach(key -> ...);
   });
   map.replace("key", "Hello world!", "Hello world again!", Duration.ofSeconds(10)).thenAccept(oldValue -> {
     ...
   });
   
 

If the provided ReadConsistency is ReadConsistency.LOCAL and local caching is enabled for the map, reads will be serviced via the cache. Otherwise, reads will fall back to ReadConsistency.SEQUENTIAL if the cache is not enabled.

Parameters:

consistency - The read consistency level.

Returns:

A completable future to be completed with the result once complete.

clear

public CompletableFuture<Void> clear()

Removes all entries from the map.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:

   
   map.clear().join();
   
 

Alternatively, to execute the operation asynchronous and be notified once the operation is complete in a different thread, use one of the many completable future callbacks:

   
   map.clear().thenRun(() -> {
     ...
   });
   
 

Returns:

A completable future to be completed once the operation is complete.

onAdd

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onAdd(Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a put(Object, Object) event listener.

Parameters:

callback - The put event callback.

Returns:

The event listener context.

onAdd

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onAdd(K key,
                                                                         Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a put(Object, Object) event listener.

Parameters:

callback - The put event callback.

Returns:

The event listener context.

onUpdate

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onUpdate(Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a put(Object, Object) event listener.

Parameters:

callback - The put event listener callback.

Returns:

The event listener context.

onUpdate

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onUpdate(K key,
                                                                            Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a put(Object, Object) event listener.

Parameters:

callback - The put event listener callback.

Returns:

The event listener context.

onRemove

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onRemove(Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a remove(Object) event listener.

Parameters:

callback - The remove event listener callback.

Returns:

The event listener context.

onRemove

public CompletableFuture<Listener<DistributedMap.EntryEvent<K,V>>> onRemove(K key,
                                                                            Consumer<DistributedMap.EntryEvent<K,V>> callback)

Registers a remove(Object) event listener.

Parameters:

callback - The remove event listener callback.

Returns:

The event listener context.

open

public CompletableFuture<DistributedMap<K,V>> open()

Specified by:

open in interface Managed<DistributedMap<K,V>>

Specified by:

open in interface io.atomix.resource.Resource<DistributedMap<K,V>>

Overrides:

open in class io.atomix.resource.AbstractResource<DistributedMap<K,V>>