com.hazelcast.core
Interface MultiMap<K,V>

All Superinterfaces:

Instance

public interface MultiMap<K,V>
extends Instance

A specialized map whose keys can be associated with multiple values.

Gotchas:

• Methods, including but not limited to get, containsKey, containsValue, remove, put, lock, unlock, do not use hashCode and equals implementations of keys, instead they use hashCode and equals of 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.

Author:

oztalip

See Also:

IMap

Nested Class Summary

Nested classes/interfaces inherited from interface com.hazelcast.core.Instance

Instance.InstanceType

Method Summary

void	addEntryListener(EntryListener<K,V> listener, boolean includeValue) Adds an entry listener for this multimap.
void	addEntryListener(EntryListener<K,V> listener, K key, boolean includeValue) Adds the specified entry listener for the specified key.
void	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.
Set<Map.Entry<K,V>>	entrySet() Returns the set of key-value pairs in the multimap.
Collection<V>	get(K key) Returns the collection of values associated with the key.
LocalMapStats	getLocalMultiMapStats() Returns LocalMultiMapStats for this map.
String	getName() Returns the name of this multimap.
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 the lock for the specified key.
boolean	lockMap(long time, TimeUnit timeunit) Tries to acquire the lock for the entire map.
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.
void	removeEntryListener(EntryListener<K,V> listener) Removes the specified entry listener Returns silently if there is no such listener added before.
void	removeEntryListener(EntryListener<K,V> listener, K key) Removes the specified entry listener for the specified key.
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.
void	unlock(K key) Releases the lock for the specified key.
void	unlockMap() Unlocks the map.
int	valueCount(K key) Returns number of values matching to given key in the multimap.
Collection<V>	values() Returns the collection of values in the multimap.

Methods inherited from interface com.hazelcast.core.Instance

destroy, getId, getInstanceType

Method Detail

getName

String getName()

Returns the name of this multimap.

Returns:

the name of this multimap

put

boolean put(K key,
            V value)

Stores a key-value pair in the multimap.

Warning:

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

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:

This method uses hashCode and equals of binary form of the key, not the actual implementations of hashCode and equals defined in 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.

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 binary form of the key, not the actual implementations of hashCode and equals defined in key's class.

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:

This method uses hashCode and equals of binary form of the key, not the actual implementations of hashCode and equals defined in 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.

Parameters:

key - the key of the entries to remove

Returns:

the collection of removed values associated with the given key. Returned collection might be modifiable but it has no effect on the multimap

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 set is NOT backed by the map, so changes to the map are NOT reflected in the set, and vice-versa.

Returns:

locally owned keys.

keySet

Set<K> keySet()

Returns the set of keys in the multimap.

Warning:

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

Returns:

the set of keys in the multimap. 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. 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 set is NOT backed by the map, so changes to the map are NOT reflected in the set, and vice-versa.

Returns:

the set of key-value pairs in the multimap. 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 binary form of the key, not the actual implementations of hashCode and equals defined in 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.

This method uses hashCode and equals of binary form of the key, not the actual implementations of hashCode and equals defined in 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.

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 number of values matching to given key in the multimap.

Warning:

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

Parameters:

key - the key whose values count are to be returned

Returns:

number of values matching to given key in the multimap.

addLocalEntryListener

void addLocalEntryListener(EntryListener<K,V> listener)

Adds a local entry listener for this multimap. 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 the some portion of the entries. Owned entries are called local entries. This listener will be listening for the events of local entries. Let's say 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

See Also:

localKeySet()

addEntryListener

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

Adds an entry listener for this multimap. Listener will get notified for all multimap add/remove/update/evict events.

Parameters:

listener - entry listener

includeValue - true if EntryEvent should contain the value.

removeEntryListener

void removeEntryListener(EntryListener<K,V> listener)

Removes the specified entry listener Returns silently if there is no such listener added before.

Parameters:

listener - entry listener

addEntryListener

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

Adds the specified entry listener for the specified key. The listener will get notified for all add/remove/update/evict events of the specified key only.

Warning:

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

Parameters:

listener - entry listener

key - the key to listen

includeValue - true if EntryEvent should contain the value.

removeEntryListener

void removeEntryListener(EntryListener<K,V> listener,
                         K key)

Removes the specified entry listener for the specified key. Returns silently if there is no such listener added before for the key.

Warning:

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

Parameters:

listener -

key -

lock

void lock(K key)

Acquires 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 the lock has been acquired.

Scope of the lock is this multimap only. 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 binary form of the key, not the actual implementations of hashCode and equals defined in key's class.

Parameters:

key - key to lock.

tryLock

boolean tryLock(K key)

Tries to acquire the lock for the specified key.

If the lock is not available then the current thread doesn't wait and returns false immediately.

Warning:

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

Parameters:

key - key to lock.

Returns:

true if lock is acquired, false otherwise.

tryLock

boolean tryLock(K key,
                long time,
                TimeUnit timeunit)

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 binary form of the key, not the actual implementations of hashCode and equals defined in 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 and false if the waiting time elapsed before the lock was acquired.

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 binary form of the key, not the actual implementations of hashCode and equals defined in key's class.

Parameters:

key - key to lock.

lockMap

boolean lockMap(long time,
                TimeUnit timeunit)

Tries to acquire the lock for the entire map. The thread that locks the map can do all the operations but other threads in the cluster cannot operate on the map.

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

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 and false if the waiting time elapsed before the lock was acquired.

unlockMap

void unlockMap()

Unlocks the map. It never blocks and returns immediately.

getLocalMultiMapStats

LocalMapStats 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, 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.