K - type of the multimap keyV - type of the multimap valuepublic interface MultiMap<K,V> extends BaseMultiMap<K,V>
Gotchas:
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.
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.
IMap| Modifier and Type | Method and Description |
|---|---|
UUID |
addEntryListener(EntryListener<K,V> listener,
boolean includeValue)
Adds an entry listener for this multimap.
|
UUID |
addEntryListener(EntryListener<K,V> listener,
K key,
boolean includeValue)
Adds the specified entry listener for the specified key.
|
UUID |
addLocalEntryListener(EntryListener<K,V> listener)
Adds a local entry listener 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(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.
|
CompletionStage<Void> |
putAllAsync(K key,
Collection<? extends V> value)
Stores the given Collection in the specified key of a MultiMap asynchronously.
|
CompletionStage<Void> |
putAllAsync(Map<? extends K,Collection<? extends V>> m)
Stores the given Map in the MultiMap asynchronously.
|
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(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,
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.
|
destroy, getDestroyContextForTenant, getName, getPartitionKey, getServiceNameCompletionStage<Void> putAllAsync(@Nonnull Map<? extends K,Collection<? extends V>> m)
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.
m - the map to be storedCompletionStage<Void> putAllAsync(@Nonnull K key, @Nonnull Collection<? extends V> value)
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.
key - the key to store tovalue - the Collection to be stored in the MultiMap keyboolean put(@Nonnull K key, @Nonnull V value)
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.
put in interface BaseMultiMap<K,V>key - the key to be storedvalue - the value to be storedtrue if size of the multimap is increased,
false if the multimap already contains the key-value pair@Nonnull Collection<V> get(@Nonnull K 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.
get in interface BaseMultiMap<K,V>key - the key whose associated values are to be returnedboolean remove(@Nonnull Object key, @Nonnull Object value)
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.
remove in interface BaseMultiMap<K,V>key - the key of the entry to removevalue - the value of the entry to removetrue if the size of the multimap changed after the remove operation,
false otherwise@Nonnull Collection<V> remove(@Nonnull Object 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.
remove in interface BaseMultiMap<K,V>key - the key of the entries to removevoid delete(@Nonnull Object 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.
key - the key of the entry to remove@Nonnull Set<K> localKeySet()
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.
@Nonnull Set<K> keySet()
Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.
@Nonnull Collection<V> values()
Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.
@Nonnull Set<Map.Entry<K,V>> entrySet()
Warning: The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.
boolean containsKey(@Nonnull K 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.
key - the key whose existence is checkedtrue if the multimap contains an entry with the key,
false otherwiseboolean containsValue(@Nonnull Object value)
value - the value whose existence is checkedtrue if the multimap contains an entry with the value,
false otherwise.boolean containsEntry(@Nonnull K key, @Nonnull V value)
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.
key - the key whose existence is checkedvalue - the value whose existence is checkedtrue if the multimap contains the key-value pair,
false otherwiseint size()
size in interface BaseMultiMap<K,V>void clear()
int valueCount(@Nonnull K 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.
valueCount in interface BaseMultiMap<K,V>key - the key whose values count is to be returned@Nonnull UUID addLocalEntryListener(@Nonnull EntryListener<K,V> listener)
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.
listener - entry listener for this multimaplocalKeySet()@Nonnull UUID addEntryListener(@Nonnull EntryListener<K,V> listener, boolean includeValue)
The listener will be notified for all multimap add/remove/update events.
listener - entry listener for this multimapincludeValue - true if EntryEvent should contain the value,
false otherwiseboolean removeEntryListener(@Nonnull UUID registrationId)
Returns silently if no such listener was added before.
registrationId - registration ID of listener@Nonnull UUID addEntryListener(@Nonnull EntryListener<K,V> listener, @Nonnull K key, boolean includeValue)
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.
listener - the entry listenerkey - the key to listen toincludeValue - true if EntryEvent should contain the value,
false otherwisevoid lock(@Nonnull K 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.
key - the key to lockvoid lock(@Nonnull K key, long leaseTime, @Nonnull TimeUnit timeUnit)
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.
key - the key to lockleaseTime - time to wait before releasing the locktimeUnit - unit of time for the lease timeboolean isLocked(@Nonnull K 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.
key - key to lock to be checked.true if the lock is acquired, false otherwise.boolean tryLock(@Nonnull K 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.
key - the key to lock.true if lock is acquired, false otherwiseboolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit) throws InterruptedException
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:
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.
time - the maximum time to wait for the locktimeunit - the time unit of the time argumenttrue if the lock was acquired, false if the
waiting time elapsed before the lock was acquiredInterruptedException - if interrupted while trying to acquire the lockboolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit, long leaseTime, @Nullable TimeUnit leaseTimeunit) throws InterruptedException
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:
hashCode and equals of
the binary form of the key, not the actual implementations of
hashCode and equals defined in the key's class.key - key to lock in this maptime - maximum time to wait for the locktimeunit - time unit of the time argumentleaseTime - time to wait before releasing the lockleaseTimeunit - unit of time to specify lease timetrue if the lock was acquired and false if the
waiting time elapsed before the lock was acquiredNullPointerException - if the specified key is nullInterruptedException - if interrupted while trying to acquire the lockvoid unlock(@Nonnull K 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.
key - the key to lockvoid forceUnlock(@Nonnull K key)
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.
key - key to lock@Nonnull LocalMultiMapStats getLocalMultiMapStats()
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.
Copyright © 2023 Hazelcast, Inc.. All rights reserved.