Interface MultiMap<K,V>
-
- Type Parameters:
K
- type of the multimap keyV
- 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
, andunlock
-- do not usehashCode
andequals
implementations of the keys. Instead, they usehashCode
andequals
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()
ReturnsLocalMultiMapStats
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.-
Methods inherited from interface com.hazelcast.core.DistributedObject
destroy, getDestroyContextForTenant, getName, getPartitionKey, getServiceName
-
-
-
-
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 tovalue
- 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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Specified by:
put
in interfaceBaseMultiMap<K,V>
- Parameters:
key
- the key to be storedvalue
- 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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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 interfaceBaseMultiMap<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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Specified by:
remove
in interfaceBaseMultiMap<K,V>
- Parameters:
key
- the key of the entry to removevalue
- 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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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 interfaceBaseMultiMap<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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
key
- the key whose existence is checkedvalue
- 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 interfaceBaseMultiMap<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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Specified by:
valueCount
in interfaceBaseMultiMap<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 multimapincludeValue
-true
ifEntryEvent
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 multimapincludeValue
-true
ifEntryEvent
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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
listener
- the entry listenerkey
- the key to listen toincludeValue
-true
ifEntryEvent
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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
key
- the key to lockleaseTime
- time to wait before releasing the locktimeUnit
- 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 returnsfalse
.Warning: This method uses
hashCode
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
time
- the maximum time to wait for the locktimeunit
- the time unit of thetime
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.
hashCode
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
key
- key to lock in this maptime
- maximum time to wait for the locktimeunit
- time unit of thetime
argumentleaseTime
- time to wait before releasing the lockleaseTimeunit
- unit of time to specify lease time- Returns:
true
if the lock was acquired andfalse
if the waiting time elapsed before the lock was acquired- Throws:
java.lang.NullPointerException
- if the specified key isnull
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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
'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
andequals
of the binary form of thekey
, not the actual implementations ofhashCode
andequals
defined in thekey
's class.- Parameters:
key
- key to lock
-
getLocalMultiMapStats
@Nonnull LocalMultiMapStats getLocalMultiMapStats()
ReturnsLocalMultiMapStats
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.
-
-