Concurrent, distributed, observable and queryable map client. More...

#include <IMap.h>

Inheritance diagram for hazelcast::client::IMap< K, V >:

Public Member Functions
bool	containsKey (const K &key)
	check if this map contains key. More...

bool	containsValue (const V &value)
	check if this map contains value. More...

boost::shared_ptr< V >	get (const K &key)
	get the value. More...

boost::shared_ptr< V >	put (const K &key, const V &value)
	put new entry into map. More...

boost::shared_ptr< V >	remove (const K &key)
	remove entry form map More...

bool	remove (const K &key, const V &value)
	removes entry from map if there is an entry with same key and value. More...

void	deleteEntry (const K &key)
	removes entry from map. More...

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

bool	tryRemove (const K &key, long timeoutInMillis)
	Tries to remove the entry with the given key from this map within specified timeout value. More...

bool	tryPut (const K &key, const V &value, long timeoutInMillis)
	Tries to put the given key, value into this map within specified timeout value. More...

boost::shared_ptr< V >	put (const K &key, const V &value, long ttlInMillis)
	Puts an entry into this map with a given ttl (time to live) value. More...

void	putTransient (const K &key, const V &value, long ttlInMillis)
	Same as put(K, V, long, TimeUnit) but MapStore, if defined, will not be called to store/persist the entry. More...

boost::shared_ptr< V >	putIfAbsent (const K &key, const V &value)
	Puts an entry into this map, if the specified key is not already associated with a value. More...

boost::shared_ptr< V >	putIfAbsent (const K &key, const V &value, long ttlInMillis)
	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. More...

bool	replace (const K &key, const V &oldValue, const V &newValue)
	Replaces the entry for a key only if currently mapped to a given value. More...

boost::shared_ptr< V >	replace (const K &key, const V &value)
	Replaces the entry for a key only if currently mapped to some value. More...

void	set (const K &key, const V &value, long ttl)
	Puts an entry into this map. More...

void	lock (const K &key)
	Acquires the lock for the specified key. More...

void	lock (const K &key, long leaseTime)
	Acquires the lock for the specified key for the specified lease time. More...

bool	isLocked (const K &key)
	Checks the lock for the specified key. More...

bool	tryLock (const K &key)
	Tries to acquire the lock for the specified key. More...

bool	tryLock (const K &key, long timeInMillis)
	Tries to acquire the lock for the specified key. More...

void	unlock (const K &key)
	Releases the lock for the specified key. More...

void	forceUnlock (const K &key)
	Releases the lock for the specified key regardless of the lock owner. More...

template<typename MapInterceptor >
std::string	addInterceptor (MapInterceptor &interceptor)
	Adds an interceptor for this map. More...

void	removeInterceptor (const std::string &id)
	Removes the given interceptor for this map. More...

std::string	addEntryListener (EntryListener< K, V > &listener, bool includeValue)
	Adds an entry listener for this map. More...

bool	removeEntryListener (const std::string &registrationId)
	Removes the specified entry listener Returns silently if there is no such listener added before. More...

std::string	addEntryListener (EntryListener< K, V > &listener, const K &key, bool includeValue)
	Adds the specified entry listener for the specified key. More...

EntryView< K, V >	getEntryView (const K &key)
	Returns the `EntryView` for the specified key. More...

bool	evict (const K &key)
	Evicts the specified key from this map. More...

void	evictAll ()
	Evicts all keys from this map except locked ones. More...

std::map< K, V >	getAll (const std::set< K > &keys)
	Returns the entries for the given keys. More...

std::vector< K >	keySet ()
	Returns a vector clone of the keys contained in this map. More...

std::vector< K >	keySet (const serialization::IdentifiedDataSerializable &predicate)
	Queries the map based on the specified predicate and returns the keys of matching entries. More...

std::vector< V >	values ()
	Returns a vector clone of the values contained in this map. More...

std::vector< V >	values (const serialization::IdentifiedDataSerializable &predicate)
	Returns a vector clone of the values contained in this map. More...

std::vector< std::pair< K, V > >	entrySet ()
	Returns a std::vector< std::pair<K, V> > clone of the mappings contained in this map. More...

std::vector< std::pair< K, V > >	entrySet (const serialization::IdentifiedDataSerializable &predicate)
	Queries the map based on the specified predicate and returns the matching entries. More...

void	addIndex (const std::string &attribute, bool ordered)
	Adds an index to this map for the specified entries so that queries can run faster. More...

template<typename ResultType , typename EntryProcessor >
boost::shared_ptr< ResultType >	executeOnKey (const K &key, EntryProcessor &entryProcessor)
	Applies the user defined EntryProcessor to the entry mapped by the key. More...

template<typename ResultType , typename EntryProcessor >
std::map< K, boost::shared_ptr < ResultType > >	executeOnEntries (EntryProcessor &entryProcessor)
	Applies the user defined EntryProcessor to the all entries in the map. More...

void	set (const K &key, const V &value)
	Puts an entry into this map. More...

int	size ()
	Returns the number of key-value mappings in this map. More...

bool	isEmpty ()
	Returns `true` if this map contains no key-value mappings. More...

void	putAll (const std::map< K, V > &entries)
	Copies all of the mappings from the specified map to this map (optional operation). More...

void	clear ()
	Removes all of the mappings from this map (optional operation). More...

Friends
class	HazelcastClient

Detailed Description

template<typename K, typename V>
class hazelcast::client::IMap< K, V >

Concurrent, distributed, observable and queryable map client.

Notice that this class have a private constructor. You can access get an IMap in the following way

 ClientConfig clientConfig;
 HazelcastClient client(clientConfig);
 IMap<int,std::string> imap = client.getMap<int,std::string>("aKey");

Parameters

<K>	key
<V>	value

Member Function Documentation

template<typename K , typename V >

std::string hazelcast::client::IMap< K, V >::addEntryListener	(	EntryListener< K, V > &	listener,
		bool	includeValue
	)

inline

Adds an entry listener for this map.

Warning 1: If listener should do a time consuming operation, off-load the operation to another thread. otherwise it will slow down the system.

Warning 2: Do not make a call to hazelcast. It can cause deadlock.

Parameters

listener	entry listener
includeValue	`true` if `EntryEvent` should contain the value.

Returns: registrationId of added listener that can be used to remove the entry listener.

template<typename K , typename V >

std::string hazelcast::client::IMap< K, V >::addEntryListener	(	EntryListener< K, V > &	listener,
		const K &	key,
		bool	includeValue
	)

inline

Adds the specified entry listener for the specified key.

Warning 1: If listener should do a time consuming operation, off-load the operation to another thread. otherwise it will slow down the system.

Warning 2: Do not make a call to hazelcast. It can cause deadlock.

Parameters

listener	entry listener
key	key to listen
includeValue	`true` if `EntryEvent` should contain the value.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::addIndex	(	const std::string &	attribute,
		bool	ordered
	)

inline

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.

class Employee : public serialization::Portable { //... private: bool active; int age; std::string name;

}

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

IMap<std::string, Employee > imap = hazelcastInstance.getMap<std::string, Employee >("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

In the server side, Index 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.

template<typename K , typename V >

template<typename MapInterceptor >

std::string hazelcast::client::IMap< K, V >::addInterceptor ( MapInterceptor & interceptor )

inline

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.

Interceptor should extend either Portable or IdentifiedSerializable. Notice that map interceptor runs on the nodes. Because of that same class should be implemented in java side with same classId and factoryId.

Parameters

interceptor map interceptor

Returns: id of registered interceptor

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::clear ( )

inline

Removes all of the mappings from this map (optional operation).

The map will be empty after this call returns.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::containsKey ( const K & key )

inline

check if this map contains key.

Parameters

key

Returns: true if contains, false otherwise

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::containsValue ( const V & value )

inline

check if this map contains value.

Parameters

value

Returns: true if contains, false otherwise

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::deleteEntry ( const K & key )

inline

removes entry from map.

Does not return anything.

Parameters

key	The key of the map entry to remove.

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

std::vector<std::pair<K, V> > hazelcast::client::IMap< K, V >::entrySet ( )

inline

Returns a std::vector< std::pair<K, V> > clone of the mappings contained in this map.

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

Returns: a vector clone of the keys mappings in this map

template<typename K , typename V >

std::vector<std::pair<K, V> > hazelcast::client::IMap< K, V >::entrySet ( const serialization::IdentifiedDataSerializable & predicate )

inline

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 vector of the query

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::evict ( const K & key )

inline

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.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::evictAll ( )

inline

Evicts all keys from this map except locked ones.

If a MapStore is defined for this map, deleteAll is not called by this method. If you do want to deleteAll to be called use the clear() method.

The EVICT_ALL event is fired for any registered listeners. See EntryListener::mapEvicted(MapEvent)}.

See Also: clear()

template<typename K , typename V >

template<typename ResultType , typename EntryProcessor >

std::map<K, boost::shared_ptr<ResultType> > hazelcast::client::IMap< K, V >::executeOnEntries ( EntryProcessor & entryProcessor )

inline

Applies the user defined EntryProcessor to the all entries in the map.

Returns the results mapped by each key in the map.

EntryProcessor should extend either Portable or IdentifiedSerializable. Notice that map EntryProcessor runs on the nodes. Because of that, same class should be implemented in java side with same classId and factoryId.

Template Parameters

ResultType	that entry processor will return
EntryProcessor	type of entry processor class

Parameters

entryProcessor that will be applied

template<typename K , typename V >

template<typename ResultType , typename EntryProcessor >

boost::shared_ptr<ResultType> hazelcast::client::IMap< K, V >::executeOnKey	(	const K &	key,
		EntryProcessor &	entryProcessor
	)

inline

Applies the user defined EntryProcessor to the entry mapped by the key.

Returns the the ResultType which is result of the process() method of EntryProcessor.

EntryProcessor should extend either Portable or IdentifiedSerializable. Notice that map EntryProcessor runs on the nodes. Because of that, same class should be implemented in java side with same classId and factoryId.

Template Parameters

EntryProcessor	type of entry processor class
ResultType	that entry processor will return

Parameters

entryProcessor	that will be applied
key	of entry that entryProcessor will be applied on

Returns: result of entry process.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::forceUnlock ( const K & key )

inline

Releases the lock for the specified key regardless of the lock owner.

It always successfully unlocks the key, never blocks and returns immediately.

Parameters

key	key to lock.

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::get ( const K & key )

inline

get the value.

Parameters

key

Returns: value value in shared_ptr, if there is no mapping for key then return NULL in shared_ptr.

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

std::map<K, V> hazelcast::client::IMap< K, V >::getAll ( const std::set< K > & keys )

inline

Returns the entries for the given keys.

Parameters

keys	keys to get

Returns: map of entries

template<typename K , typename V >

EntryView<K, V> hazelcast::client::IMap< K, V >::getEntryView ( const K & key )

inline

Returns the EntryView for the specified key.

Parameters

key	key of the entry

Returns: EntryView of the specified key

See Also: EntryView

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::isEmpty ( )

inline

Returns true if this map contains no key-value mappings.

Returns: true if this map contains no key-value mappings

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::isLocked ( const K & key )

inline

Checks the lock for the specified key.

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

Parameters

key	key to lock to be checked.

Returns: true if lock is acquired, false otherwise.

template<typename K , typename V >

std::vector<K> hazelcast::client::IMap< K, V >::keySet ( )

inline

Returns a vector clone of the keys contained in this map.

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

Returns: a vector clone of the keys contained in this map

template<typename K , typename V >

std::vector<K> hazelcast::client::IMap< K, V >::keySet ( const serialization::IdentifiedDataSerializable & predicate )

inline

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

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::lock ( const K & key )

inline

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.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::lock	(	const K &	key,
		long	leaseTime
	)

inline

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.

Parameters

key	key to lock.
leaseTime	time in milliseconds to wait before releasing the lock.

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::put	(	const K &	key,
		const V &	value
	)

inline

put new entry into map.

Parameters

key
value

Returns: the previous value in shared_ptr, if there is no mapping for key

Exceptions

IClassCastException if the type of the specified elements are incompatible with the server side. then returns NULL in shared_ptr.

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::put	(	const K &	key,
		const V &	value,
		long	ttlInMillis
	)

inline

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.

Parameters

key	key of the entry
value	value of the entry
ttlInMillis	maximum time for this entry to stay in the map in milliseconds,0 means infinite.

Returns: the previous value in shared_ptr, if there is no mapping for key then returns NULL in shared_ptr.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::putAll ( const std::map< K, V > & entries )

inline

Copies all of the mappings from the specified map to this map (optional operation).

The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Parameters

m	mappings to be stored in this map

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::putIfAbsent	(	const K &	key,
		const V &	value
	)

inline

Puts an entry into this map, if the specified key is not already associated with a value.

Parameters

key	key with which the specified value is to be associated
value

Returns: the previous value in shared_ptr, if there is no mapping for key then returns NULL in shared_ptr.

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::putIfAbsent	(	const K &	key,
		const V &	value,
		long	ttlInMillis
	)

inline

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
ttlInMillis	maximum time in milliseconds for this entry to stay in the map

Returns: the previous value of the entry, if there is no mapping for key then returns NULL in shared_ptr.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::putTransient	(	const K &	key,
		const V &	value,
		long	ttlInMillis
	)

inline

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.

Parameters

key	key of the entry
value	value of the entry
ttlInMillis	maximum time for this entry to stay in the map in milliseconds, 0 means infinite.

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::remove ( const K & key )

inline

remove entry form map

Parameters

key

Returns: the previous value in shared_ptr, if there is no mapping for key then returns NULL in shared_ptr.

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::remove	(	const K &	key,
		const V &	value
	)

inline

removes entry from map if there is an entry with same key and value.

Parameters

key
value

Returns: true if remove is successful false otherwise

Exceptions

IClassCastException if the type of the specified element is incompatible with the server side.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::removeEntryListener ( const std::string & registrationId )

inline

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

Parameters

registrationId id of registered listener

Returns: true if registration is removed, false otherwise

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::removeInterceptor ( const std::string & id )

inline

Removes the given interceptor for this map.

So it will not intercept operations anymore.

Parameters

id	registration id of map interceptor

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::replace	(	const K &	key,
		const V &	oldValue,
		const V &	newValue
	)

inline

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

Parameters

key	key with which the specified value is associated
oldValue	value expected to be associated with the specified key
newValue

Returns: true if the value was replaced

template<typename K , typename V >

boost::shared_ptr<V> hazelcast::client::IMap< K, V >::replace	(	const K &	key,
		const V &	value
	)

inline

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

Parameters

key	key with which the specified value is associated
value

Returns: the previous value of the entry, if there is no mapping for key then returns NULL in shared_ptr.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::set	(	const K &	key,
		const V &	value,
		long	ttl
	)

inline

Puts an entry into this map.

Similar to put operation except that set doesn't return the old value which is more efficient.

Parameters

key	key with which the specified value is associated
value
ttl	maximum time in milliseconds for this entry to stay in the map 0 means infinite.

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::set	(	const K &	key,
		const V &	value
	)

inline

Puts an entry into this map.

Similar to put operation except that set doesn't return the old value which is more efficient.

Parameters

key
value

template<typename K , typename V >

int hazelcast::client::IMap< K, V >::size ( )

inline

Returns the number of key-value mappings in this map.

If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns: the number of key-value mappings in this map

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::tryLock ( const K & key )

inline

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.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::tryLock	(	const K &	key,
		long	timeInMillis
	)

inline

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
timeInMillis	maximum time in milliseconds to wait for the lock

Returns: true if the lock was acquired and false if the waiting time elapsed before the lock was acquired.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::tryPut	(	const K &	key,
		const V &	value,
		long	timeoutInMillis
	)

inline

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
timeoutInMillis	maximum time to wait in milliseconds

Returns: true if the put is successful, false otherwise.

template<typename K , typename V >

bool hazelcast::client::IMap< K, V >::tryRemove	(	const K &	key,
		long	timeoutInMillis
	)

inline

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
timeoutInMillis	maximum time in milliseconds to wait for acquiring the lock for the key

template<typename K , typename V >

void hazelcast::client::IMap< K, V >::unlock ( const K & key )

inline

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.

Parameters

key	key to lock.

Exceptions

IllegalMonitorStateException if the current thread does not hold this lock MTODO

template<typename K , typename V >

std::vector<V> hazelcast::client::IMap< K, V >::values ( )

inline

Returns a vector clone of the values contained in this map.

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

Returns: a vector clone of the values contained in this map

template<typename K , typename V >

std::vector<V> hazelcast::client::IMap< K, V >::values ( const serialization::IdentifiedDataSerializable & predicate )

inline

Returns a vector clone of the values contained in this map.

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

Parameters

predicate the criteria for values to match

Returns: a vector clone of the values contained in this map

The documentation for this class was generated from the following file:

hazelcast/include/hazelcast/client/IMap.h

Public Member Functions

Friends

Detailed Description

template<typename K, typename V> class hazelcast::client::IMap< K, V >

Member Function Documentation

template<typename K, typename V>
class hazelcast::client::IMap< K, V >