Interface ReplicatedMap<K,​V extends ReplicatedData>

  • Type Parameters:
    K - The type of keys.
    V - The replicated data type to be used for values.
    All Superinterfaces:
    ReplicatedData

    public interface ReplicatedMap<K,​V extends ReplicatedData>
    extends 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 Detail

      • 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:
        java.util.NoSuchElementException - if the key is not preset in the map
      • getOrElse

        V getOrElse​(K key,
                    java.util.function.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

        java.util.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,
                                                                          java.util.function.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 ReplicatedDataReplicatedMap<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