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:

  • Method Details

    • putAllAsync

      CompletionStage<Void> putAllAsync(@Nonnull Map<? extends K,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 e.g. 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

      CompletionStage<Void> putAllAsync(@Nonnull K key, @Nonnull 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 e.g. 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 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 Object key, @Nonnull 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 Collection<V> remove(@Nonnull 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 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 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 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 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 Set<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 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 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:

    • addLocalEntryListener

      @Nonnull 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 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 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 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 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 TimeUnit timeunit) throws 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:
      InterruptedException - if interrupted while trying to acquire the lock

    • tryLock

      boolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit, long leaseTime, @Nullable TimeUnit leaseTimeunit) throws 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:
      NullPointerException - if the specified key is null
      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 multimap and contains information such as ownedEntryCount backupEntryCount, lastUpdateTime, and lockedEntryCount.

      Since these stats are only for the local portion of this multimap, 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.