Package kalix.javasdk.replicatedentity

Interface ReplicatedMap<K,V extends kalix.replicatedentity.ReplicatedData>

Type Parameters:
K - The type of keys.
V - The replicated data type to be used for values.
All Superinterfaces:
kalix.replicatedentity.ReplicatedData
public interface ReplicatedMap<K,V extends kalix.replicatedentity.ReplicatedData> extends kalix.replicatedentity.ReplicatedData
A Replicated Map that allows both the addition and removal of ReplicatedData objects.

Use the more specialized maps if possible, such as ReplicatedCounterMap, ReplicatedRegisterMap, and ReplicatedMultiMap.

A removal can only be done if all of the additions that caused the key to be in the map have been seen by this node. This means that, for example, if node 1 adds key A, and node 2 also adds key A, then node 1's addition is replicated to node 3, and node 3 deletes it before node 2's addition is replicated, then the item will still be in the map because node 2's addition had not yet been observed by node 3. However, if both additions had been replicated to node 3, then the key will be removed.

The values of the map are themselves ReplicatedData types, and hence allow concurrent updates that will eventually converge. New ReplicatedData objects may only be created when using the getOrElse(Object, Function) method, using the provided ReplicatedDataFactory for the create function.

While removing entries from the map is supported, if the entries are added back again, it is possible that the value of the deleted entry may be merged into the value of the current entry, depending on whether the removal has been replicated to all nodes before the addition is performed.

The map may contain different data types as values, however, for a given key, the type must never change. If two different types for the same key are inserted on different nodes, the replicated entity will enter an invalid state that can never be merged, and behavior of the replicated entity is undefined.

Care needs to be taken to ensure that the serialized value of keys in the set is stable. For example, if using protobufs, the serialized value of any maps contained in the protobuf is not stable, and can yield a different set of bytes for the same logically equal element. Hence maps should be avoided. Additionally, some changes in protobuf schemas which are backwards compatible from a protobuf perspective, such as changing from sint32 to int32, do result in different serialized bytes, and so must be avoided.

  • Method Details

    • get

      V get(K key)
      Get the ReplicatedData value for the given key.
      Parameters:
      key - the key of the mapping
      Returns:
      the ReplicatedData for the key
      Throws:
      NoSuchElementException - if the key is not preset in the map

    • getOrElse

      V getOrElse(K key, Function<ReplicatedDataFactory,V> create)
      Get the ReplicatedData value for the given key. If the key is not present in the map, then a new value is created with a creation function.
      Parameters:
      key - the key of the mapping
      create - function used to create an empty value using the given ReplicatedDataFactory if the key is not present in the map
      Returns:
      the ReplicatedData for the key

    • update

      ReplicatedMap<K,V> update(K key, V value)
      Update the ReplicatedData value associated with the given key.
      Parameters:
      key - the key of the mapping
      value - the updated ReplicatedData value
      Returns:
      a new map with the updated value

    • remove

      ReplicatedMap<K,V> remove(K key)
      Remove the mapping for a key if it is present.
      Parameters:
      key - key whose mapping is to be removed from the map
      Returns:
      a new map with the removed mapping

    • clear

      ReplicatedMap<K,V> clear()
      Remove all entries from this map.
      Returns:
      a new empty map

    • size

      int size()
      Get the number of key-value mappings in this map.
      Returns:
      the number of key-value mappings in this map

    • isEmpty

      boolean isEmpty()
      Check whether this map is empty.
      Returns:
      true if this map contains no key-value mappings

    • containsKey

      boolean containsKey(K key)
      Check whether this map contains a mapping for the given key.
      Parameters:
      key - key whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the given key

    • keySet

      Set<K> keySet()
      Get a Set view of the keys contained in this map.
      Returns:
      the keys contained in this map

    • getReplicatedCounter

      default ReplicatedCounter getReplicatedCounter(K key)
      Get a ReplicatedCounter from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Parameters:
      key - the key for a Replicated Counter in this map
      Returns:
      the ReplicatedCounter associated with the given key, or an empty counter

    • getReplicatedRegister

      default <ValueT> ReplicatedRegister<ValueT> getReplicatedRegister(K key)
      Get a ReplicatedRegister from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      ValueT - the value type for the Replicated Register
      Parameters:
      key - the key for a Replicated Register in this map
      Returns:
      the ReplicatedRegister associated with the given key, or an empty register

    • getReplicatedRegister

      default <ValueT> ReplicatedRegister<ValueT> getReplicatedRegister(K key, Supplier<ValueT> defaultValue)
      Get a ReplicatedRegister from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      ValueT - the value type for the Replicated Register
      Parameters:
      key - the key for a Replicated Register in this map
      defaultValue - the supplier for a default value when the register is not present
      Returns:
      the ReplicatedRegister associated with the given key, or a default register

    • getReplicatedSet

      default <ElementT> ReplicatedSet<ElementT> getReplicatedSet(K key)
      Get a ReplicatedSet from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      ElementT - the element type for the Replicated Set
      Parameters:
      key - the key for a Replicated Set in this map
      Returns:
      the ReplicatedSet associated with the given key, or an empty set

    • getReplicatedCounterMap

      default <KeyT> ReplicatedCounterMap<KeyT> getReplicatedCounterMap(K key)
      Get a ReplicatedCounterMap from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      KeyT - the key type for the Replicated Counter Map
      Parameters:
      key - the key for a Replicated Counter Map in this map
      Returns:
      the ReplicatedCounterMap associated with the given key, or an empty map

    • getReplicatedRegisterMap

      default <KeyT, ValueT> ReplicatedRegisterMap<KeyT,ValueT> getReplicatedRegisterMap(K key)
      Get a ReplicatedRegisterMap from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      KeyT - the key type for the Replicated Register Map
      ValueT - the value type for the Replicated Register Map
      Parameters:
      key - the key for a Replicated Register Map in this map
      Returns:
      the ReplicatedRegisterMap associated with the given key, or an empty map

    • getReplicatedMultiMap

      default <KeyT, ValueT> ReplicatedMultiMap<KeyT,ValueT> getReplicatedMultiMap(K key)
      Get a ReplicatedMultiMap from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      KeyT - the key type for the Replicated Multi-Map
      ValueT - the value type for the Replicated Multi-Map
      Parameters:
      key - the key for a Replicated Multi-Map in this map
      Returns:
      the ReplicatedMultiMap associated with the given key, or an empty multi-map

    • getReplicatedMap

      default <KeyT, ValueT extends kalix.replicatedentity.ReplicatedData> ReplicatedMap<KeyT,ValueT> getReplicatedMap(K key)
      Get a ReplicatedMap from a heterogeneous Replicated Map (a map with different types of Replicated Data values).
      Type Parameters:
      KeyT - the key type for the Replicated Map
      ValueT - the value type for the Replicated Map
      Parameters:
      key - the key for a Replicated Map in this map
      Returns:
      the ReplicatedMap associated with the given key, or an empty map