com.hazelcast.core

## Interface MultiMap<K,V>

- Type Parameters:
    `K` - type of the multimap key
    `V` - type of the multimap value
  All Superinterfaces:
    BaseMultiMap<K,V>, DistributedObject
  All Known Implementing Classes:
    ClientMultiMapProxy

      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 Quorum `QuorumConfig` since 3.10 in cluster versions 3.10 and higher.

  See Also:
    `IMap`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `addEntryListener(EntryListener<K,V> listener, boolean includeValue)` Adds an entry listener for this multimap.
    `String` | `addEntryListener(EntryListener<K,V> listener, K key, boolean includeValue)` Adds the specified entry listener for the specified key.
    `String` | `addLocalEntryListener(EntryListener<K,V> listener)` Adds a local entry listener for this multimap.
    `<SuppliedValue,Result> Result` | `aggregate(Supplier<K,V,SuppliedValue> supplier, Aggregation<K,SuppliedValue,Result> aggregation)` Deprecated. The old Aggregations API is superseded by Fast Aggregations (`com.hazelcast.aggregation`) which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
    `<SuppliedValue,Result> Result` | `aggregate(Supplier<K,V,SuppliedValue> supplier, Aggregation<K,SuppliedValue,Result> aggregation, JobTracker jobTracker)` Deprecated. The old Aggregations API is superseded by Fast Aggregations (`com.hazelcast.aggregation`) which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
    `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(Object value)` Returns whether the multimap contains an entry with the value.
    `void` | `delete(Object key)` Deletes all the entries with the given key.
    `Set<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.
    `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.
    `Set<K>` | `keySet()` Returns the set of keys in the multimap.
    `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, 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.
    `Collection<V>` | `remove(Object key)` Removes all the entries with the given key.
    `boolean` | `remove(Object key, Object value)` Removes the given key value pair from the multimap.
    `boolean` | `removeEntryListener(String 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, TimeUnit timeunit)` Tries to acquire the lock for the specified key.
    `boolean` | `tryLock(K key, long time, TimeUnit timeunit, long leaseTime, 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.
    `Collection<V>` | `values()` Returns the collection of values in the multimap.

    - ### Methods inherited from interface com.hazelcast.core.DistributedObject

      `destroy, getName, getPartitionKey, getServiceName`

- - ### Method Detail

    - #### put

          boolean put(K key,
                      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

    - #### get

          Collection<V> get(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(Object key,
                         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

          Collection<V> remove(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(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

          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

          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

          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

          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(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(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(K key,
                                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.
      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(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

          String addLocalEntryListener(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.

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

    - #### addEntryListener

          String addEntryListener(EntryListener<K,V> listener,
                                  boolean includeValue)

      Adds an entry listener for this multimap.

      The listener will be notified for all multimap add/remove/update/evict 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(String 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

          String addEntryListener(EntryListener<K,V> listener,
                                  K key,
                                  boolean includeValue)

      Adds the specified entry listener for the specified key.

      The listener will be notified for all add/remove/update/evict 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(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(K key,
                    long leaseTime,
                    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(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(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(K key,
                          long time,
                          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`

    - #### tryLock

          boolean tryLock(K key,
                          long time,
                          TimeUnit timeunit,
                          long leaseTime,
                          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`

    - #### unlock

          void unlock(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(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

          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.

    - #### aggregate

          @Deprecated
          <SuppliedValue,Result> Result aggregate(Supplier<K,V,SuppliedValue> supplier,
                                                              Aggregation<K,SuppliedValue,Result> aggregation)

      Deprecated. The old Aggregations API is superseded by Fast Aggregations (`com.hazelcast.aggregation`) which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
      Executes a predefined aggregation on the multimaps data set.

      The `Supplier` is used to either select or to select and extract a (sub-)value. A predefined set of aggregations can be found in `Aggregations`.

      Method does not honor Quorum.

      Type Parameters:
        `SuppliedValue` - the final type emitted from the supplier
        `Result` - the resulting aggregation value type
      Parameters:
        `supplier` - the supplier to select and / or extract a (sub-)value from the multimap
        `aggregation` - the aggregation that is being executed against the multimap
      Returns:
        Returns the aggregated value for the multimaps data set

    - #### aggregate

          @Deprecated
          <SuppliedValue,Result> Result aggregate(Supplier<K,V,SuppliedValue> supplier,
                                                              Aggregation<K,SuppliedValue,Result> aggregation,
                                                              JobTracker jobTracker)

      Deprecated. The old Aggregations API is superseded by Fast Aggregations (`com.hazelcast.aggregation`) which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
      Executes a predefined aggregation on the multimaps data set.

      The `Supplier` is used to either select, or to select and extract, a (sub-)value. A predefined set of aggregations can be found in `Aggregations`.

      Method does not honor Quorum.

      Type Parameters:
        `SuppliedValue` - the final type emitted from the supplier
        `Result` - the resulting aggregation value type
      Parameters:
        `supplier` - the supplier to select and / or extract a (sub-)value from the multimap
        `aggregation` - the aggregation that is being executed against the multimap
        `jobTracker` - the `JobTracker` instance to execute the aggregation
      Returns:
        Returns the aggregated value

Copyright © 2019. All rights reserved.