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

Type Parameters:

K - key

V - value

All Superinterfaces:

ConcurrentMap<K,V>, Instance, Map<K,V>

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

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.

Read more: http://kickjava.com/src/java/util/IdentityHashMap.java.htm#ixzz1TCesQMzr

Nested Class Summary

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

Map.Entry<K,V>

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 map.
void	addEntryListener(EntryListener<K,V> listener, K key, boolean includeValue) Adds the specified entry listener for the specified key.
void	addIndex(Expression<?> expression, boolean ordered) Adds an index to this map based on the provided expression.
void	addIndex(String attribute, boolean ordered) Adds an index to this map for the specified entries so that queries can run faster.
void	addLocalEntryListener(EntryListener<K,V> listener) Adds a local entry listener for 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(Object key) Evicts the specified key from this map.
void	flush() If this map has a MapStore and write-delay-seconds is bigger than 0 (write-behind) then this method flushes all the local dirty entries by calling MapStore.storeAll()
Map<K,V>	getAll(Set<K> keys) Returns the entries for the given keys.
Future<V>	getAsync(K key) Asynchronously gets the given key.
LocalMapStats	getLocalMapStats() Returns LocalMapStats for this map.
MapEntry<K,V>	getMapEntry(K key) Returns the MapEntry for the specified key.
String	getName() Returns the name of 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.
boolean	lockMap(long time, TimeUnit timeunit) Tries to acquire the lock for the entire map.
V	put(K key, V value, long ttl, TimeUnit timeunit) Puts an entry into this map with a given ttl (time to live) value.
void	putAndUnlock(K key, V value) Puts the key and value into this map and unlocks the key if the calling thread owns the lock.
Future<V>	putAsync(K key, V value) Asynchronously puts the given key and 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.
Future<V>	removeAsync(K key) Asynchronously removes the given key.
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.
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.
V	tryLockAndGet(K key, long time, TimeUnit timeunit) Tries to acquire the lock for the specified key and returns the value of the key if lock is required in time.
boolean	tryPut(K key, V value, long timeout, TimeUnit timeunit) Tries to put the given key, value into this map within specified timeout value.
Object	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.
void	unlockMap() Unlocks the 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.concurrent.ConcurrentMap

putIfAbsent, remove, replace, replace

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from interface com.hazelcast.core.Instance

destroy, getId, getInstanceType

Method Detail

flush

void flush()

If this map has a MapStore and write-delay-seconds is bigger than 0 (write-behind) then this method flushes all the local dirty entries by calling MapStore.storeAll()

getName

String getName()

Returns the name of this map

Returns:

name of this map

getAll

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

Returns the entries for the given keys.

Parameters:

keys - keys to get

Returns:

map of entries

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.

Parameters:

key - the key of the map entry

Returns:

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

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.

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.

See Also:

Future

removeAsync

Future<V> removeAsync(K key)

Asynchronously removes the given key.

Parameters:

key - The key of the map entry to remove.

Returns:

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

tryRemove

Object tryRemove(K key,
                 long timeout,
                 TimeUnit timeunit)
                 throws TimeoutException

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.

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:

removed value of the entry

Throws:

TimeoutException - if lock cannot be acquired for the given key within timeout

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.

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.

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.

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

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.

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

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.

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

tryLockAndGet

V tryLockAndGet(K key,
                long time,
                TimeUnit timeunit)
                throws TimeoutException

Tries to acquire the lock for the specified key and returns the value of the key if lock is required in time.

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:

key - key of the entry

time - maximum time to wait for the lock

timeunit - time unit of the time argument.

Returns:

value of the key in this map

Throws:

TimeoutException - if lock cannot be acquired in time.

putAndUnlock

void putAndUnlock(K key,
                  V value)

Puts the key and value into this map and unlocks the key if the calling thread owns the lock.

Parameters:

key - key of the entry

value - value of the entry

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

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.

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

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.

unlock

void unlock(K key)

Releases the lock for the specified key. It never blocks and returns immediately.

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

unlockMap

void unlockMap()

Unlocks the map. It never blocks and returns immediately.

addLocalEntryListener

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

addEntryListener

void 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

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.

Parameters:

listener - entry listener

key - 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.

Parameters:

listener -

key -

getMapEntry

MapEntry<K,V> getMapEntry(K key)

Returns the MapEntry for the specified key.

Parameters:

key - key of the entry

Returns:

MapEntry of the specified key

See Also:

MapEntry

evict

boolean evict(Object 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.

Parameters:

key - key to evict

Returns:

true if the key is evicted, false otherwise.

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.

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.

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.

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.

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.

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.

addIndex

void addIndex(Expression<?> expression,
              boolean ordered)

Adds an index to this map based on the provided expression.

Parameters:

expression - expression for the index.

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.