Package io.atomix.client.map

Interface AsyncAtomicMap<K,V>

All Superinterfaces:
AsyncPrimitive<AsyncAtomicMap<K,V>,AtomicMap<K,V>>, DistributedPrimitive
public interface AsyncAtomicMap<K,V> extends AsyncPrimitive<AsyncAtomicMap<K,V>,AtomicMap<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.

  • Method Details

    • size

      CompletableFuture<Integer> size()
      Returns the number of entries in the map.
      Returns:
      a future for map size.

    • isEmpty

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

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

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

      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

      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 CompletableFuture<Versioned<V>> computeIfAbsent(K key, 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 CompletableFuture<Versioned<V>> computeIfPresent(K key, 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 CompletableFuture<Versioned<V>> compute(K key, 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

      CompletableFuture<Versioned<V>> computeIf(K key, Predicate<? super V> condition, 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

      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.

    • put

      CompletableFuture<Versioned<V>> put(K key, V value, Duration ttl)
      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
      ttl - the time to live after which to remove the value
      Returns:
      the previous value (and version) associated with key, or null if there was no mapping for key.

    • putAndGet

      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.

    • putAndGet

      CompletableFuture<Versioned<V>> putAndGet(K key, V value, Duration ttl)
      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
      ttl - the time to live after which to remove the value
      Returns:
      new value.

    • remove

      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

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

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

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

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

      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.

    • putIfAbsent

      CompletableFuture<Versioned<V>> putIfAbsent(K key, V value, Duration ttl)
      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
      ttl - the time to live after which to remove the value
      Returns:
      the previous value associated with the specified key or null if key does not already mapped to a value.

    • remove

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

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

      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

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

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

    • lock

      CompletableFuture<Void> lock(K key)
      Acquires a lock on the given key.
      Parameters:
      key - the key for which to acquire the lock
      Returns:
      the lock version

    • tryLock

      CompletableFuture<Boolean> tryLock(K key)
      Attempts to acquire a lock on the given key.
      Parameters:
      key - the key for which to acquire the lock
      Returns:
      an optional long containing the version of the key at the time it was locked

    • tryLock

      default CompletableFuture<Boolean> tryLock(K key, long timeout, TimeUnit unit)
      Attempts to acquire a lock on the given key.
      Parameters:
      key - the key for which to acquire the lock
      timeout - the lock timeout
      unit - the lock unit
      Returns:
      an optional long containing the version of the key at the time it was locked

    • tryLock

      CompletableFuture<Boolean> tryLock(K key, Duration timeout)
      Attempts to acquire a lock on the given key.
      Parameters:
      key - the key for which to acquire the lock
      timeout - the lock timeout
      Returns:
      an optional long containing the version of the key at the time it was locked

    • isLocked

      CompletableFuture<Boolean> isLocked(K key)
      Returns a boolean indicating whether a lock is currently held on the given key.
      Parameters:
      key - the key for which to determine whether a lock exists
      Returns:
      indicates whether a lock exists on the given key

    • unlock

      CompletableFuture<Void> unlock(K key)
      Releases a lock on the given key.
      Parameters:
      key - the key for which to release the lock

    • listen

      default CompletableFuture<Cancellable> listen(AtomicMapEventListener<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

    • listen

      CompletableFuture<Cancellable> listen(AtomicMapEventListener<K,V> listener, 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

    • sync

      default AtomicMap<K,V> sync(Duration operationTimeout)
      Description copied from interface: AsyncPrimitive
      Returns a synchronous wrapper around the asynchronous primitive.
      Specified by:
      sync in interface AsyncPrimitive<K,V>
      Parameters:
      operationTimeout - the synchronous operation timeout
      Returns:
      the synchronous primitive