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

Type Parameters:

K - key

V - value

All Superinterfaces:

BaseMap<K,V>, ConcurrentMap<K,V>, DistributedObject, Map<K,V>

public interface IMap<K,V>
extends ConcurrentMap<K,V>, BaseMap<K,V>

Concurrent, distributed, observable and queryable map.

This class is not a general-purpose ConcurrentMap implementation! While this class implements the Map interface, it intentionally violates Map's general contract, which mandates the use of the equals method when comparing objects. Instead of the equals method this implementation compares the serialized byte version of the objects.

Gotchas:

• Methods, including but not limited to get, containsKey, containsValue, evict, remove, put, putIfAbsent, replace, lock, unlock, do not use hashCode and equals implementations of keys, instead they use hashCode and equals of binary (serialized) forms of the objects.
• get method returns a clone of original values, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes. For additional info see get(Object).
• Methods, including but not limited to 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.

This class does not allow null to be used as a key or value.

See Also:

ConcurrentMap

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

String	addEntryListener(EntryListener<K,V> listener, boolean includeValue) Adds an entry listener for this map.
String	addEntryListener(EntryListener<K,V> listener, K key, boolean includeValue) Adds the specified entry listener for the specified key.
String	addEntryListener(EntryListener<K,V> listener, Predicate<K,V> predicate, boolean includeValue) Adds an continuous entry listener for this map.
String	addEntryListener(EntryListener<K,V> listener, Predicate<K,V> predicate, K key, boolean includeValue) Adds an continuous entry listener for this map.
void	addIndex(String attribute, boolean ordered) Adds an index to this map for the specified entries so that queries can run faster.
String	addInterceptor(com.hazelcast.map.MapInterceptor interceptor) Adds an interceptor for this map.
String	addLocalEntryListener(EntryListener<K,V> listener) Adds a local entry listener for this map.
String	addLocalEntryListener(EntryListener<K,V> listener, Predicate<K,V> predicate, boolean includeValue) Adds a local entry listener for this map.
String	addLocalEntryListener(EntryListener<K,V> listener, Predicate<K,V> predicate, K key, boolean includeValue) Adds a local entry listener for this map.
boolean	containsKey(Object key) Returns true if this map contains an entry for the specified key.
boolean	containsValue(Object value)
void	delete(Object key) Removes the mapping for a key from this map if it is present (optional operation).
Set<Map.Entry<K,V>>	entrySet() Returns a Set clone of the mappings contained in this map.
Set<Map.Entry<K,V>>	entrySet(Predicate predicate) Queries the map based on the specified predicate and returns the matching entries.
boolean	evict(K key) Evicts the specified key from this map.
Map<K,Object>	executeOnEntries(com.hazelcast.map.EntryProcessor entryProcessor) Applies the user defined EntryProcessor to the all entries in the map.
Map<K,Object>	executeOnEntries(com.hazelcast.map.EntryProcessor entryProcessor, Predicate predicate) Applies the user defined EntryProcessor to the entries in the map which satisfies provided predicate.
Object	executeOnKey(K key, com.hazelcast.map.EntryProcessor entryProcessor) Applies the user defined EntryProcessor to the entry mapped by the key.
Map<K,Object>	executeOnKeys(Set<K> keys, com.hazelcast.map.EntryProcessor entryProcessor) Applies the user defined EntryProcessor to the entries mapped by the collection of keys.
void	flush() If this map has a MapStore this method flushes all the local dirty entries by calling MapStore.storeAll() and/or MapStore.deleteAll()
void	forceUnlock(K key) Releases the lock for the specified key regardless of the lock owner.
V	get(Object key) Returns the value for the specified key, or null if this map does not contain this key.
Map<K,V>	getAll(Set<K> keys) Returns the entries for the given keys.
Future<V>	getAsync(K key) Asynchronously gets the given key.
EntryView<K,V>	getEntryView(K key) Returns the EntryView for the specified key.
LocalMapStats	getLocalMapStats() Returns LocalMapStats for this map.
boolean	isLocked(K key) Checks the lock for the specified key.
Set<K>	keySet() Returns a set clone of the keys contained in this map.
Set<K>	keySet(Predicate predicate) Queries the map based on the specified predicate and returns the keys of matching entries.
Set<K>	localKeySet() Returns the locally owned set of keys.
Set<K>	localKeySet(Predicate predicate) Returns the keys of matching locally owned entries.
void	lock(K key) Acquires the 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.
V	put(K key, V value) Associates the specified value with the specified key in this map If the map previously contained a mapping for the key, the old value is replaced by the specified value.
V	put(K key, V value, long ttl, TimeUnit timeunit) Puts an entry into this map with a given ttl (time to live) value.
Future<V>	putAsync(K key, V value) Asynchronously puts the given key and value.
Future<V>	putAsync(K key, V value, long ttl, TimeUnit timeunit) Asynchronously puts the given key and value into this map with a given ttl (time to live) value.
V	putIfAbsent(K key, V value) If the specified key is not already associated with a value, associate it with the given value.
V	putIfAbsent(K key, V value, long ttl, TimeUnit timeunit) Puts an entry into this map with a given ttl (time to live) value if the specified key is not already associated with a value.
void	putTransient(K key, V value, long ttl, TimeUnit timeunit) Same as #put(K, V, long, TimeUnit) but MapStore, if defined, will not be called to store/persist the entry.
V	remove(Object key) Removes the mapping for a key from this map if it is present.
boolean	remove(Object key, Object value) Removes the entry for a key only if currently mapped to a given value.
Future<V>	removeAsync(K key) Asynchronously removes the given key.
boolean	removeEntryListener(String id) Removes the specified entry listener Returns silently if there is no such listener added before.
void	removeInterceptor(String id) Removes the given interceptor for this map.
V	replace(K key, V value) Replaces the entry for a key only if currently mapped to some value.
boolean	replace(K key, V oldValue, V newValue) Replaces the entry for a key only if currently mapped to a given value.
void	set(K key, V value) Puts an entry into this map.
void	set(K key, V value, long ttl, TimeUnit timeunit) Puts an entry into this map with a given ttl (time to live) value.
Future	submitToKey(K key, com.hazelcast.map.EntryProcessor entryProcessor) Applies the user defined EntryProcessor to the entry mapped by the key.
void	submitToKey(K key, com.hazelcast.map.EntryProcessor entryProcessor, ExecutionCallback callback) Applies the user defined EntryProcessor to the entry mapped by the key with specified ExecutionCallback to listen event status and returns immediately.
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	tryPut(K key, V value, long timeout, TimeUnit timeunit) Tries to put the given key, value into this map within specified timeout value.
boolean	tryRemove(K key, long timeout, TimeUnit timeunit) Tries to remove the entry with the given key from this map within specified timeout value.
void	unlock(K key) Releases the lock for the specified key.
Collection<V>	values() Returns a collection clone of the values contained in this map.
Collection<V>	values(Predicate predicate) Queries the map based on the specified predicate and returns the values of matching entries.

Methods inherited from interface java.util.Map

clear, equals, hashCode, isEmpty, putAll, size

Methods inherited from interface com.hazelcast.core.BaseMap

isEmpty, size

Methods inherited from interface com.hazelcast.core.DistributedObject

destroy, getId, getName, getPartitionKey, getServiceName

Method Detail

containsKey

boolean containsKey(Object key)

Returns true if this map contains an entry for the specified 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.

Specified by:

containsKey in interface BaseMap<K,V>

Specified by:

containsKey in interface Map<K,V>

Parameters:

key - key

Returns:

true if this map contains an entry for the specified key

Throws:

NullPointerException - if the specified key is null

containsValue

boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

Throws:

NullPointerException - if the specified value is null

get

V get(Object key)

Returns the value for the specified key, or null if this map does not contain this key.

Warning:

This method returns a clone of original value, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.

      V value = map.get(key);
      value.updateSomeProperty();
      map.put(key, value);
 

Warning-2:

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.

Specified by:

get in interface BaseMap<K,V>

Specified by:

get in interface Map<K,V>

Parameters:

key - key

Returns:

value

Throws:

NullPointerException - if the specified key is null

put

V put(K key,
      V value)

Associates the specified value with the specified key in this map If the map previously contained a mapping for the key, the old value is replaced by the specified value.

Warning:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Warning-2:

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.

Specified by:

put in interface BaseMap<K,V>

Specified by:

put in interface Map<K,V>

Parameters:

key - key

value - value

Returns:

previous value associated with key or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key or value is null

remove

V remove(Object key)

Removes the mapping for a key from this map if it is present.

The map will not contain a mapping for the specified key once the call returns.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Specified by:

remove in interface BaseMap<K,V>

Specified by:

remove in interface Map<K,V>

Parameters:

key - key

Returns:

previous value associated with key or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key is null

remove

boolean remove(Object key,
               Object value)

Removes the entry for a key only if currently mapped to a given value. This is equivalent to

   if (map.containsKey(key) && map.get(key).equals(value)) {
       map.remove(key);
       return true;
   } else return false;

except that the action is performed atomically.

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.

Specified by:

remove in interface BaseMap<K,V>

Specified by:

remove in interface ConcurrentMap<K,V>

Parameters:

key - key

value - value

Returns:

true if the value was removed

Throws:

NullPointerException - if the specified key or value is null

delete

void delete(Object key)

Removes the mapping for a key from this map if it is present (optional operation).

Differently from remove(Object); this operation does not return removed value to avoid serialization cost of returned value. If the removed value will not be used, delete operation should be preferred over remove operation for a better performance.

The map will not contain a mapping for the specified key once the call returns.

Specified by:

delete in interface BaseMap<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Throws:

ClassCastException - if the key is of an inappropriate type for this map (optional)

NullPointerException - if the specified key is null

flush

void flush()

If this map has a MapStore this method flushes all the local dirty entries by calling MapStore.storeAll() and/or MapStore.deleteAll()

getAll

Map<K,V> getAll(Set<K> keys)

Returns the entries for the given keys.

Warning:

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

Warning-2:

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

Parameters:

keys - keys to get

Returns:

map of entries

Throws:

NullPointerException - if any of the specified keys are null

getAsync

Future<V> getAsync(K key)

Asynchronously gets the given key. Future future = map.getAsync(key); // do some other stuff, when ready get the result Object value = future.get(); Future.get() will block until the actual map.get() completes. If the application requires timely response, then Future.get(timeout, timeunit) can be used. try{ Future future = map.getAsync(key); Object value = future.get(40, TimeUnit.MILLISECOND); }catch (TimeoutException t) { // time wasn't enough } ExecutionException is never thrown.

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 map entry

Returns:

Future from which the value of the key can be retrieved.

Throws:

NullPointerException - if the specified key is null

See Also:

Future

putAsync

Future<V> putAsync(K key,
                   V value)

Asynchronously puts the given key and value. Future future = map.putAsync(key, value); // do some other stuff, when ready get the result Object oldValue = future.get(); Future.get() will block until the actual map.get() completes. If the application requires timely response, then Future.get(timeout, timeunit) can be used. try{ Future future = map.putAsync(key, newValue); Object oldValue = future.get(40, TimeUnit.MILLISECOND); }catch (TimeoutException t) { // time wasn't enough } ExecutionException is never thrown.

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 map entry

value - the new value of the map entry

Returns:

Future from which the old value of the key can be retrieved.

Throws:

NullPointerException - if the specified key or value is null

See Also:

Future

putAsync

Future<V> putAsync(K key,
                   V value,
                   long ttl,
                   TimeUnit timeunit)

Asynchronously puts the given key and value into this map with a given ttl (time to live) value. Entry will expire and get evicted after the ttl. If ttl is 0, then the entry lives forever. Future future = map.putAsync(key, value, ttl, timeunit); // do some other stuff, when ready get the result Object oldValue = future.get(); Future.get() will block until the actual map.get() completes. If the application requires timely response, then Future.get(timeout, timeunit) can be used. try{ Future future = map.putAsync(key, newValue, ttl, timeunit); Object oldValue = future.get(40, TimeUnit.MILLISECOND); }catch (TimeoutException t) { // time wasn't enough } ExecutionException is never thrown.

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 map entry

value - the new value of the map entry

ttl - maximum time for this entry to stay in the map 0 means infinite.

timeunit - time unit for the ttl

Returns:

Future from which the old value of the key can be retrieved.

Throws:

NullPointerException - if the specified key or value is null

See Also:

Future

removeAsync

Future<V> removeAsync(K key)

Asynchronously removes 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.

Parameters:

key - The key of the map entry to remove.

Returns:

A Future from which the value removed from the map can be retrieved.

Throws:

NullPointerException - if the specified key is null

tryRemove

boolean tryRemove(K key,
                  long timeout,
                  TimeUnit timeunit)

Tries to remove the entry with the given key from this map within specified timeout value. If the key is already locked by another thread and/or member, then this operation will wait timeout amount for acquiring the lock.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Parameters:

key - key of the entry

timeout - maximum time to wait for acquiring the lock for the key

timeunit - time unit for the timeout

Returns:

true if the remove is successful, false otherwise.

Throws:

NullPointerException - if the specified key is null

tryPut

boolean tryPut(K key,
               V value,
               long timeout,
               TimeUnit timeunit)

Tries to put the given key, value into this map within specified timeout value. If this method returns false, it means that the caller thread couldn't acquire the lock for the key within timeout duration, thus put operation is not successful.

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 of the entry

value - value of the entry

timeout - maximum time to wait

timeunit - time unit for the timeout

Returns:

true if the put is successful, false otherwise.

Throws:

NullPointerException - if the specified key or value is null

put

V put(K key,
      V value,
      long ttl,
      TimeUnit timeunit)

Puts an entry into this map with a given ttl (time to live) value. Entry will expire and get evicted after the ttl. If ttl is 0, then the entry lives forever.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map 0 means infinite.

timeunit - time unit for the ttl

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key or value is null

putTransient

void putTransient(K key,
                  V value,
                  long ttl,
                  TimeUnit timeunit)

Same as #put(K, V, long, TimeUnit) but MapStore, if defined, will not be called to store/persist the entry. If ttl is 0, then the entry lives forever.

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 of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map. 0 means infinite.

timeunit - time unit for the ttl

Throws:

NullPointerException - if the specified key or value is null

putIfAbsent

V putIfAbsent(K key,
              V value)

If the specified key is not already associated with a value, associate it with the given value. This is equivalent to

   if (!map.containsKey(key))
       return map.put(key, value);
   else
       return map.get(key);

except that the action is performed atomically.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Specified by:

putIfAbsent in interface BaseMap<K,V>

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Parameters:

key - key

value - value

Returns:

previous value associated with key or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key or value is null

putIfAbsent

V putIfAbsent(K key,
              V value,
              long ttl,
              TimeUnit timeunit)

Puts an entry into this map with a given ttl (time to live) value if the specified key is not already associated with a value. Entry will expire and get evicted after the ttl.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map

timeunit - time unit for the ttl

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key or value is null

replace

boolean replace(K key,
                V oldValue,
                V newValue)

Replaces the entry for a key only if currently mapped to a given value. This is equivalent to

   if (map.containsKey(key) && map.get(key).equals(oldValue)) {
       map.put(key, newValue);
       return true;
   } else return false;

except that the action is performed atomically.

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.

Specified by:

replace in interface BaseMap<K,V>

Specified by:

replace in interface ConcurrentMap<K,V>

Parameters:

key - key

oldValue - old value

newValue - new value

Returns:

true if the value was replaced

Throws:

NullPointerException - if any of the specified parameters are null

replace

V replace(K key,
          V value)

Replaces the entry for a key only if currently mapped to some value. This is equivalent to

   if (map.containsKey(key)) {
       return map.put(key, value);
   } else return null;

except that the action is performed atomically.

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:

This method returns a clone of previous value, not the original (identically equal) value previously put into map.

Specified by:

replace in interface BaseMap<K,V>

Specified by:

replace in interface ConcurrentMap<K,V>

Parameters:

key - key

value - value

Returns:

previous value associated with key or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key or value is null

set

void set(K key,
         V value)

Puts an entry into this map. Similar to put operation except that set doesn't return the old value which is more efficient.

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.

Specified by:

set in interface BaseMap<K,V>

Parameters:

key - key of the entry

value - value of the entry

Throws:

NullPointerException - if the specified key or value is null

set

void set(K key,
         V value,
         long ttl,
         TimeUnit timeunit)

Puts an entry into this map with a given ttl (time to live) value. Entry will expire and get evicted after the ttl. If ttl is 0, then the entry lives forever. Similar to put operation except that set doesn't return the old value which is more efficient.

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 of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map 0 means infinite.

timeunit - time unit for the ttl

Throws:

NullPointerException - if the specified key or value is null

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.

You get a lock whether the value is present in the map or not. Other threads (possibly on other systems) would block on their invoke of lock() until the non-existent key is unlocked. If the lock holder introduces the key to the map, the put() operation is not blocked. If a thread not holding a lock on the non-existent key tries to introduce the key while a lock exists on the non-existent key, the put() operation blocks until it is unlocked.

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

Parameters:

key - key to lock.

Throws:

NullPointerException - if the specified key is null

lock

void lock(K key,
          long leaseTime,
          TimeUnit timeUnit)

Acquires the lock for the specified key for the specified lease time.

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

Parameters:

key - key to lock.

leaseTime - time to wait before releasing the lock.

timeUnit - unit of time to specify lease time.

Throws:

NullPointerException - if the specified key is null

isLocked

boolean isLocked(K key)

Checks the lock for the specified key.

If the lock is acquired then returns true, else false.

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 to be checked.

Returns:

true if lock is acquired, false otherwise.

Throws:

NullPointerException - if the specified key is null

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.

Throws:

NullPointerException - if the specified key is null

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

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.

If the current thread is the holder of this lock then the hold count is decremented. If the hold count is now zero then the lock is released. If the current thread is not the holder of this lock then IllegalMonitorStateException is thrown.

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.

Throws:

NullPointerException - if the specified key is null

IllegalMonitorStateException - if the current thread does not hold this 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 binary form of the key, not the actual implementations of hashCode and equals defined in key's class.

Parameters:

key - key to lock.

Throws:

NullPointerException - if the specified key is null

addLocalEntryListener

String addLocalEntryListener(EntryListener<K,V> listener)

Adds a local entry listener for this map. Added listener will be only listening for the events (add/remove/update/evict) of the locally owned entries.

Note that entries in distributed map 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 map.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()

addLocalEntryListener

String addLocalEntryListener(EntryListener<K,V> listener,
                             Predicate<K,V> predicate,
                             boolean includeValue)

Adds a local entry listener for this map. Added listener will be only listening for the events (add/remove/update/evict) of the locally owned entries. Listener will get notified for map add/remove/update/evict events filtered by given predicate.

Parameters:

listener - entry listener

predicate - predicate for filtering entries

includeValue - true if EntryEvent should contain the value.

Returns:

addLocalEntryListener

String addLocalEntryListener(EntryListener<K,V> listener,
                             Predicate<K,V> predicate,
                             K key,
                             boolean includeValue)

Adds a local entry listener for this map. Added listener will be only listening for the events (add/remove/update/evict) of the locally owned entries. Listener will get notified for map add/remove/update/evict events filtered by given predicate.

Parameters:

listener - entry listener

predicate - predicate for filtering entries

key - key to listen

includeValue - true if EntryEvent should contain the value.

Returns:

addInterceptor

String addInterceptor(com.hazelcast.map.MapInterceptor interceptor)

Adds an interceptor for this map. Added interceptor will intercept operations and execute user defined methods and will cancel operations if user defined method throw exception.

Parameters:

interceptor - map interceptor

Returns:

id of registered interceptor

removeInterceptor

void removeInterceptor(String id)

Removes the given interceptor for this map. So it will not intercept operations anymore.

Parameters:

id - registration id of map interceptor

addEntryListener

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

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

Parameters:

listener - entry listener

includeValue - true if EntryEvent should contain the value.

removeEntryListener

boolean removeEntryListener(String id)

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

Parameters:

id - id of registered 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 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 - key to listen

includeValue - true if EntryEvent should contain the value.

Throws:

NullPointerException - if the specified key is null

addEntryListener

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

Adds an continuous entry listener for this map. Listener will get notified for map add/remove/update/evict events filtered by given predicate.

Parameters:

listener - entry listener

predicate - predicate for filtering entries

includeValue - true if EntryEvent should contain the value.

addEntryListener

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

Adds an continuous entry listener for this map. Listener will get notified for map add/remove/update/evict events filtered by given predicate.

Parameters:

listener - entry listener

predicate - predicate for filtering entries

key - key to listen

includeValue - true if EntryEvent should contain the value.

getEntryView

EntryView<K,V> getEntryView(K key)

Returns the EntryView for the specified key.

Warning:

This method returns a clone of original mapping, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.

Warning-2:

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 of the entry

Returns:

EntryView of the specified key

Throws:

NullPointerException - if the specified key is null

See Also:

EntryView

evict

boolean evict(K key)

Evicts the specified key from this map. If a MapStore defined for this map, then the entry is not deleted from the underlying MapStore, evict only removes the entry from the memory.

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 evict

Returns:

true if the key is evicted, false otherwise.

Throws:

NullPointerException - if the specified key is null

keySet

Set<K> keySet()

Returns a set clone of the keys contained in this map. The set is NOT backed by the map, so changes to the map are NOT reflected in the set, and vice-versa.

Specified by:

keySet in interface Map<K,V>

Returns:

a set clone of the keys contained in this map

values

Collection<V> values()

Returns a collection clone of the values contained in this map. The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection, and vice-versa.

Specified by:

values in interface Map<K,V>

Returns:

a collection clone of the values contained in this map

entrySet

Set<Map.Entry<K,V>> entrySet()

Returns a Set clone of the mappings contained in this map. The set is NOT backed by the map, so changes to the map are NOT reflected in the set, and vice-versa.

Specified by:

entrySet in interface Map<K,V>

Returns:

a set clone of the keys mappings in this map

keySet

Set<K> keySet(Predicate predicate)

Queries the map based on the specified predicate and returns the keys of matching entries.

Specified predicate runs on all members in parallel.

Warning:

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

Parameters:

predicate - query criteria

Returns:

result key set of the query

entrySet

Set<Map.Entry<K,V>> entrySet(Predicate predicate)

Queries the map based on the specified predicate and returns the matching entries.

Specified predicate runs on all members in parallel.

Warning:

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

Parameters:

predicate - query criteria

Returns:

result entry set of the query

values

Collection<V> values(Predicate predicate)

Queries the map based on the specified predicate and returns the values of matching entries.

Specified predicate runs on all members in parallel.

Warning:

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

Parameters:

predicate - query criteria

Returns:

result value collection of the query

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.

localKeySet

Set<K> localKeySet(Predicate predicate)

Returns the keys of matching locally owned entries.

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.

Parameters:

predicate - query criteria

Returns:

keys of matching locally owned entries.

addIndex

void addIndex(String attribute,
              boolean ordered)

Adds an index to this map for the specified entries so that queries can run faster.

Let's say your map values are Employee objects.

   public class Employee implements Serializable {
       private boolean active = false;
       private int age;
       private String name = null;
       // other fields.

       // getters setter

   }
 

If you are querying your values mostly based on age and active then you should consider indexing these fields.

   IMap imap = Hazelcast.getMap("employees");
   imap.addIndex("age", true);        // ordered, since we have ranged queries for this field
   imap.addIndex("active", false);    // not ordered, because boolean field cannot have range
 

Index attribute should either have a getter method or be public. You should also make sure to add the indexes before adding entries to this map.

Parameters:

attribute - attribute of value

ordered - true if index should be ordered, false otherwise.

getLocalMapStats

LocalMapStats getLocalMapStats()

Returns LocalMapStats for this map. LocalMapStats is the statistics for the local portion of this distributed map and contains information such as ownedEntryCount backupEntryCount, lastUpdateTime, lockedEntryCount.

Since this stats are only for the local portion of this map, if you need the cluster-wide MapStats then you need to get the LocalMapStats from all members of the cluster and combine them.

Returns:

this map's local statistics.

executeOnKey

Object executeOnKey(K key,
                    com.hazelcast.map.EntryProcessor entryProcessor)

Applies the user defined EntryProcessor to the entry mapped by the key. Returns the the object which is result of the process() method of EntryProcessor.

Returns:

result of entry process.

Throws:

NullPointerException - if the specified key is null

executeOnKeys

Map<K,Object> executeOnKeys(Set<K> keys,
                            com.hazelcast.map.EntryProcessor entryProcessor)

Applies the user defined EntryProcessor to the entries mapped by the collection of keys. the results mapped by each key in the collection.

Returns:

result of entry process.

Throws:

NullPointerException - if the specified key is null

submitToKey

void submitToKey(K key,
                 com.hazelcast.map.EntryProcessor entryProcessor,
                 ExecutionCallback callback)

Applies the user defined EntryProcessor to the entry mapped by the key with specified ExecutionCallback to listen event status and returns immediately.

Parameters:

key - key to be processed

entryProcessor - processor to process the key

callback - to listen whether operation is finished or not

submitToKey

Future submitToKey(K key,
                   com.hazelcast.map.EntryProcessor entryProcessor)

Applies the user defined EntryProcessor to the entry mapped by the key. Returns immediately with a Future representing that task. EntryProcessor is not cancellable, so calling Future.cancel() method won't cancel the operation of EntryProcessor.

Parameters:

key - key to be processed

entryProcessor - processor to process the key

Returns:

Future from which the result of the operation can be retrieved.

See Also:

Future

executeOnEntries

Map<K,Object> executeOnEntries(com.hazelcast.map.EntryProcessor entryProcessor)

Applies the user defined EntryProcessor to the all entries in the map. Returns the results mapped by each key in the map.

executeOnEntries

Map<K,Object> executeOnEntries(com.hazelcast.map.EntryProcessor entryProcessor,
                               Predicate predicate)

Applies the user defined EntryProcessor to the entries in the map which satisfies provided predicate. Returns the results mapped by each key in the map.