Package com.hazelcast.multimap

Interface MultiMap<K,​V>

  • Type Parameters:
    K - type of the multimap key
    V - type of the multimap value
    All Superinterfaces:
    BaseMultiMap<K,​V>, DistributedObject
    public interface MultiMap<K,​V>
extends BaseMultiMap<K,​V>
    A specialized map whose keys can be associated with multiple values.

    Gotchas:

    • Methods -- including but not limited to get, containsKey, containsValue, remove, put, lock, and unlock -- do not use hashCode and equals implementations of the keys. Instead, they use hashCode and equals of the binary (serialized) forms of the objects.
    • Methods -- including but not limited to get, remove, keySet, values, entrySet -- return a collection clone of the values. The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

    Supports split brain protection SplitBrainProtectionConfig since 3.10 in cluster versions 3.10 and higher.

    See Also:
    IMap

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.UUID addEntryListener​(EntryListener<K,​V> listener, boolean includeValue)
      Adds an entry listener for this multimap.
      java.util.UUID addEntryListener​(EntryListener<K,​V> listener, K key, boolean includeValue)
      Adds the specified entry listener for the specified key.
      java.util.UUID addLocalEntryListener​(EntryListener<K,​V> listener)
      Adds a local entry listener for this multimap.
      java.util.UUID addLocalEntryListener​(EntryListener<K,​V> listener, boolean includeValue)
      addLocalEntryListener(EntryListener) Adds a local entry listener with ability to configure if event should contain the value for this multimap.
      void clear()
      Clears the multimap.
      boolean containsEntry​(K key, V value)
      Returns whether the multimap contains the given key-value pair.
      boolean containsKey​(K key)
      Returns whether the multimap contains an entry with the key.
      boolean containsValue​(java.lang.Object value)
      Returns whether the multimap contains an entry with the value.
      void delete​(java.lang.Object key)
      Deletes all the entries with the given key.
      java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
      Returns the set of key-value pairs in the multimap.
      void forceUnlock​(K key)
      Releases the lock for the specified key regardless of the lock owner.
      java.util.Collection<V> get​(K key)
      Returns the collection of values associated with the key.
      LocalMultiMapStats getLocalMultiMapStats()
      Returns LocalMultiMapStats for this map.
      boolean isLocked​(K key)
      Checks the lock for the specified key.
      java.util.Set<K> keySet()
      Returns the set of keys in the multimap.
      java.util.Set<K> localKeySet()
      Returns the locally owned set of keys.
      void lock​(K key)
      Acquires a lock for the specified key.
      void lock​(K key, long leaseTime, java.util.concurrent.TimeUnit timeUnit)
      Acquires the lock for the specified key for the specified lease time.
      boolean put​(K key, V value)
      Stores a key-value pair in the multimap.
      java.util.concurrent.CompletionStage<java.lang.Void> putAllAsync​(java.util.Map<? extends K,​java.util.Collection<? extends V>> m)
      Stores the given Map in the MultiMap asynchronously.
      java.util.concurrent.CompletionStage<java.lang.Void> putAllAsync​(K key, java.util.Collection<? extends V> value)
      Stores the given Collection in the specified key of a MultiMap asynchronously.
      java.util.Collection<V> remove​(java.lang.Object key)
      Removes all the entries with the given key.
      boolean remove​(java.lang.Object key, java.lang.Object value)
      Removes the given key value pair from the multimap.
      boolean removeEntryListener​(java.util.UUID registrationId)
      Removes the specified entry listener.
      int size()
      Returns the number of key-value pairs in the multimap.
      boolean tryLock​(K key)
      Tries to acquire the lock for the specified key.
      boolean tryLock​(K key, long time, java.util.concurrent.TimeUnit timeunit)
      Tries to acquire the lock for the specified key.
      boolean tryLock​(K key, long time, java.util.concurrent.TimeUnit timeunit, long leaseTime, java.util.concurrent.TimeUnit leaseTimeunit)
      Tries to acquire the lock for the specified key for the specified lease time.
      void unlock​(K key)
      Releases the lock for the specified key.
      int valueCount​(K key)
      Returns the number of values that match the given key in the multimap.
      java.util.Collection<V> values()
      Returns the collection of values in the multimap.

    • Method Detail

      • putAllAsync

        java.util.concurrent.CompletionStage<java.lang.Void> putAllAsync​(@Nonnull
                                                                 java.util.Map<? extends K,​java.util.Collection<? extends V>> m)
        Stores the given Map in the MultiMap asynchronously.

        The results of concurrently mutating the given map are undefined.

        No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.

        Warning: There is no warning if the input Map collection items are discarded due to uniqueness eg. passing in List into a Set type MultiMap

        Warning: The Map and result of the put cannot be fetched from the Future.

        Parameters:
        m - the map to be stored
        Returns:
        a void CompletionStage
        Since:
        4.1

      • putAllAsync

        java.util.concurrent.CompletionStage<java.lang.Void> putAllAsync​(@Nonnull
                                                                 K key,
                                                                 @Nonnull
                                                                 java.util.Collection<? extends V> value)
        Stores the given Collection in the specified key of a MultiMap asynchronously.

        The results of concurrently mutating the given Collection are undefined.

        No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.

        Warning: There is no warning if the input Collection items are discarded due to uniqueness eg. passing in List into a Set type MultiMap

        Warning: The Map and result of the put cannot be fetched from the Future.

        Parameters:
        key - the key to store to
        value - the Collection to be stored in the MultiMap key
        Returns:
        a void CompletionStage
        Since:
        4.1

      • put

        boolean put​(@Nonnull
            K key,
            @Nonnull
            V value)
        Stores a key-value pair in the multimap.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Specified by:
        put in interface BaseMultiMap<K,​V>
        Parameters:
        key - the key to be stored
        value - the value to be stored
        Returns:
        true if size of the multimap is increased, false if the multimap already contains the key-value pair and doesn't allow duplicates

      • get

        @Nonnull
java.util.Collection<V> get​(@Nonnull
                            K key)
        Returns the collection of values associated with the key.

        Warning 1: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Warning 2: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Specified by:
        get in interface BaseMultiMap<K,​V>
        Parameters:
        key - the key whose associated values are to be returned
        Returns:
        the collection of the values associated with the key

      • remove

        boolean remove​(@Nonnull
               java.lang.Object key,
               @Nonnull
               java.lang.Object value)
        Removes the given key value pair from the multimap.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Specified by:
        remove in interface BaseMultiMap<K,​V>
        Parameters:
        key - the key of the entry to remove
        value - the value of the entry to remove
        Returns:
        true if the size of the multimap changed after the remove operation, false otherwise

      • remove

        @Nonnull
java.util.Collection<V> remove​(@Nonnull
                               java.lang.Object key)
        Removes all the entries with the given key.

        Warning 1: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Warning 2: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Specified by:
        remove in interface BaseMultiMap<K,​V>
        Parameters:
        key - the key of the entries to remove
        Returns:
        the collection of removed values associated with the given key. The returned collection might be modifiable but it has no effect on the multimap.

      • delete

        void delete​(@Nonnull
            java.lang.Object key)
        Deletes all the entries with the given key.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key of the entry to remove

      • localKeySet

        @Nonnull
java.util.Set<K> localKeySet()
        Returns the locally owned set of keys.

        Each key in this map is owned and managed by a specific member in the cluster.

        Note that ownership of these keys might change over time so that key ownerships can be almost evenly distributed in the cluster.

        Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Returns:
        the locally owned keys

      • keySet

        @Nonnull
java.util.Set<K> keySet()
        Returns the set of keys in the multimap.

        Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Returns:
        the set of keys in the multimap (the returned set might be modifiable but it has no effect on the multimap)

      • values

        @Nonnull
java.util.Collection<V> values()
        Returns the collection of values in the multimap.

        Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Returns:
        the collection of values in the multimap (the returned collection might be modifiable but it has no effect on the multimap)

      • entrySet

        @Nonnull
java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Returns the set of key-value pairs in the multimap.

        Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

        Returns:
        the set of key-value pairs in the multimap (the returned set might be modifiable but it has no effect on the multimap)

      • containsKey

        boolean containsKey​(@Nonnull
                    K key)
        Returns whether the multimap contains an entry with the key.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key whose existence is checked
        Returns:
        true if the multimap contains an entry with the key, false otherwise

      • containsValue

        boolean containsValue​(@Nonnull
                      java.lang.Object value)
        Returns whether the multimap contains an entry with the value.
        Parameters:
        value - the value whose existence is checked
        Returns:
        true if the multimap contains an entry with the value, false otherwise.

      • containsEntry

        boolean containsEntry​(@Nonnull
                      K key,
                      @Nonnull
                      V value)
        Returns whether the multimap contains the given key-value pair.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key whose existence is checked
        value - the value whose existence is checked
        Returns:
        true if the multimap contains the key-value pair, false otherwise

      • size

        int size()
        Returns the number of key-value pairs in the multimap. If the multimap contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
        Specified by:
        size in interface BaseMultiMap<K,​V>
        Returns:
        the number of key-value pairs in the multimap

      • clear

        void clear()
        Clears the multimap. Removes all key-value pairs.

      • valueCount

        int valueCount​(@Nonnull
               K key)
        Returns the number of values that match the given key in the multimap.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Specified by:
        valueCount in interface BaseMultiMap<K,​V>
        Parameters:
        key - the key whose values count is to be returned
        Returns:
        the number of values that match the given key in the multimap

      • addLocalEntryListener

        @Nonnull
java.util.UUID addLocalEntryListener​(@Nonnull
                                     EntryListener<K,​V> listener)
        Adds a local entry listener for this multimap.

        The added listener will be only listening for the events (add/remove/update) of the locally owned entries.

        Note that entries in distributed multimap are partitioned across the cluster members; each member owns and manages some portion of the entries. Owned entries are called local entries. This listener will be listening for the events of local entries.

        For example your cluster has member1 and member2. On member2 you added a local listener, and from member1, you call multimap.put(key2, value2). If the key2 is owned by member2, then the local listener will be notified for the add/update event. Also note that entries can migrate to other nodes for load balancing and/or membership change.

        Note that event will not contain value. To configure if event should contain value, use addLocalEntryListener(EntryListener, boolean)

        Parameters:
        listener - entry listener for this multimap
        Returns:
        returns registration ID for the entry listener
        See Also:
        localKeySet()

      • addLocalEntryListener

        @Nonnull
java.util.UUID addLocalEntryListener​(@Nonnull
                                     EntryListener<K,​V> listener,
                                     boolean includeValue)
        addLocalEntryListener(EntryListener) Adds a local entry listener with ability to configure if event should contain the value for this multimap.
        Parameters:
        listener - entry listener for this multimap
        includeValue - true if EntryEvent should contain the value, false otherwise
        Returns:
        returns registration ID for the entry listener
        Since:
        5.1

      • addEntryListener

        @Nonnull
java.util.UUID addEntryListener​(@Nonnull
                                EntryListener<K,​V> listener,
                                boolean includeValue)
        Adds an entry listener for this multimap.

        The listener will be notified for all multimap add/remove/update events.

        Parameters:
        listener - entry listener for this multimap
        includeValue - true if EntryEvent should contain the value, false otherwise
        Returns:
        returns registration ID for the entry listener

      • removeEntryListener

        boolean removeEntryListener​(@Nonnull
                            java.util.UUID registrationId)
        Removes the specified entry listener.

        Returns silently if no such listener was added before.

        Parameters:
        registrationId - registration ID of listener
        Returns:
        true if registration is removed, false otherwise

      • addEntryListener

        @Nonnull
java.util.UUID addEntryListener​(@Nonnull
                                EntryListener<K,​V> listener,
                                @Nonnull
                                K key,
                                boolean includeValue)
        Adds the specified entry listener for the specified key.

        The listener will be notified for all add/remove/update events for the specified key only.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        listener - the entry listener
        key - the key to listen to
        includeValue - true if EntryEvent should contain the value, false otherwise
        Returns:
        returns registration ID

      • lock

        void lock​(@Nonnull
          K key)
        Acquires a lock for the specified key.

        If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

        The scope of the lock is for this multimap only. The acquired lock is only for the key in this multimap.

        Locks are re-entrant, so if the key is locked N times, then it should be unlocked N times before another thread can acquire it.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key to lock

      • lock

        void lock​(@Nonnull
          K key,
          long leaseTime,
          @Nonnull
          java.util.concurrent.TimeUnit timeUnit)
        Acquires the lock for the specified key for the specified lease time.

        After the lease time, the lock will be released.

        If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

        Scope of the lock is for this map only.The acquired lock is only for the key in this map.

        Locks are re-entrant, so if the key is locked N times, then it should be unlocked N times before another thread can acquire it.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key to lock
        leaseTime - time to wait before releasing the lock
        timeUnit - unit of time for the lease time

      • isLocked

        boolean isLocked​(@Nonnull
                 K key)
        Checks the lock for the specified key.

        If the lock is acquired, this method returns true, else it returns false.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - key to lock to be checked.
        Returns:
        true if the lock is acquired, false otherwise.

      • tryLock

        boolean tryLock​(@Nonnull
                K key)
        Tries to acquire the lock for the specified key.

        If the lock is not available, then the current thread does not wait and the method returns false immediately.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key to lock.
        Returns:
        true if lock is acquired, false otherwise

      • tryLock

        boolean tryLock​(@Nonnull
                K key,
                long time,
                @Nullable
                java.util.concurrent.TimeUnit timeunit)
         throws java.lang.InterruptedException
        Tries to acquire the lock for the specified key.

        If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

        • the lock is acquired by the current thread, or
        • the specified waiting time elapses.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        time - the maximum time to wait for the lock
        timeunit - the time unit of the time argument
        Returns:
        true if the lock was acquired, false if the waiting time elapsed before the lock was acquired
        Throws:
        java.lang.InterruptedException - if interrupted while trying to acquire the lock

      • tryLock

        boolean tryLock​(@Nonnull
                K key,
                long time,
                @Nullable
                java.util.concurrent.TimeUnit timeunit,
                long leaseTime,
                @Nullable
                java.util.concurrent.TimeUnit leaseTimeunit)
         throws java.lang.InterruptedException
        Tries to acquire the lock for the specified key for the specified lease time.

        After lease time, the lock will be released.

        If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

        • the lock is acquired by the current thread, or
        • the specified waiting time elapses.
        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.
        Parameters:
        key - key to lock in this map
        time - maximum time to wait for the lock
        timeunit - time unit of the time argument
        leaseTime - time to wait before releasing the lock
        leaseTimeunit - unit of time to specify lease time
        Returns:
        true if the lock was acquired and false if the waiting time elapsed before the lock was acquired
        Throws:
        java.lang.NullPointerException - if the specified key is null
        java.lang.InterruptedException - if interrupted while trying to acquire the lock

      • unlock

        void unlock​(@Nonnull
            K key)
        Releases the lock for the specified key.

        It never blocks and returns immediately.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - the key to lock

      • forceUnlock

        void forceUnlock​(@Nonnull
                 K key)
        Releases the lock for the specified key regardless of the lock owner.

        It always successfully unlocks the key, never blocks and returns immediately.

        Warning: This method uses hashCode and equals of the binary form of the key, not the actual implementations of hashCode and equals defined in the key's class.

        Parameters:
        key - key to lock

      • getLocalMultiMapStats

        @Nonnull
LocalMultiMapStats getLocalMultiMapStats()
        Returns LocalMultiMapStats for this map.

        LocalMultiMapStats is the statistics for the local portion of this distributed multi map and contains information such as ownedEntryCount backupEntryCount, lastUpdateTime, and lockedEntryCount.

        Since this stats are only for the local portion of this multi map, if you need the cluster-wide MultiMapStats, then you need to get the LocalMapStats from all members of the cluster and combine them.

        Returns:
        this multimap's local statistics.