Package org.onosproject.store.service

Interface EventuallyConsistentMap<K,​V>

  • All Superinterfaces:
    DistributedPrimitive
    public interface EventuallyConsistentMap<K,​V>
extends DistributedPrimitive
    A distributed, eventually consistent map.

    This map does not offer read after writes consistency. Operations are serialized via the timestamps issued by the clock service. If two updates are in conflict, the update with the more recent timestamp will endure.

    The interface is mostly similar to Map with some minor semantic changes and the addition of a listener framework (because the map can be mutated by clients on other instances, not only through the local Java API).

    Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notifications of update to the map.

    Null values are not allowed in this map.

    • Method Detail

      • size

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

      • isEmpty

        boolean isEmpty()
        Returns true if this map is empty.
        Returns:
        true if this map is empty, otherwise false

      • containsKey

        boolean containsKey​(K key)
        Returns true if the map contains a mapping for the specified key.
        Parameters:
        key - the key to check if this map contains
        Returns:
        true if this map has a mapping for the key, otherwise false

      • containsValue

        boolean containsValue​(V value)
        Returns true if the map contains a mapping from any key to the specified value.
        Parameters:
        value - the value to check if this map has a mapping for
        Returns:
        true if this map has a mapping to this value, otherwise false

      • get

        V get​(K key)
        Returns the value mapped to the specified key.
        Parameters:
        key - the key to look up in this map
        Returns:
        the value mapped to the key, or null if no mapping is found

      • put

        void put​(K key,
         V value)
        Associates the specified value to the specified key in this map.

        Note: this differs from the specification of Map because it does not return the previous value associated with the key. Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.

        Null values are not allowed in the map.

        Parameters:
        key - the key to add a mapping for in this map
        value - the value to associate with the key in this map

      • remove

        V remove​(K key)
        Removes the mapping associated with the specified key from the map.

        Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.

        Parameters:
        key - the key to remove the mapping for
        Returns:
        previous value associated with key, or null if there was no mapping for key.

      • remove

        void remove​(K key,
            V value)
        Removes the given key-value mapping from the map, if it exists.

        This actually means remove any values up to and including the timestamp given by the map's timestampProvider. Any mappings that produce an earlier timestamp than this given key-value pair will be removed, and any mappings that produce a later timestamp will supersede this remove.

        Note: this differs from the specification of Map because it does not return a boolean indication whether a value was removed. Clients are expected to register an EventuallyConsistentMapListener if they are interested in receiving notification of updates to the map.

        Parameters:
        key - the key to remove the mapping for
        value - the value mapped to the key

      • compute

        V compute​(K key,
          java.util.function.BiFunction<K,​V,​V> recomputeFunction)
        Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).

        If the function returns null, the mapping is removed (or remains absent if initially absent).

        Parameters:
        key - map key
        recomputeFunction - function to recompute a new value
        Returns:
        new value

      • putAll

        void putAll​(java.util.Map<? extends K,​? extends V> m)
        Adds mappings for all key-value pairs in the specified map to this map.

        This will be more efficient in communication than calling individual put operations.

        Parameters:
        m - a map of values to add to this map

      • clear

        void clear()
        Removes all mappings from this map.

      • keySet

        java.util.Set<K> keySet()
        Returns a set of the keys in this map. Changes to the set are not reflected back to the map.
        Returns:
        set of keys in the map

      • values

        java.util.Collection<V> values()
        Returns a collections of values in this map. Changes to the collection are not reflected back to the map.
        Returns:
        collection of values in the map

      • entrySet

        java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Returns a set of mappings contained in this map. Changes to the set are not reflected back to the map.
        Returns:
        set of key-value mappings in this map

      • addListener

        void addListener​(EventuallyConsistentMapListener<K,​V> listener)
        Adds the specified listener to the map which will be notified whenever the mappings in the map are changed.
        Parameters:
        listener - listener to register for events

      • removeListener

        void removeListener​(EventuallyConsistentMapListener<K,​V> listener)
        Removes the specified listener from the map such that it will no longer receive change notifications.
        Parameters:
        listener - listener to deregister for events