Hazelcast C++ Client
 All Classes Functions Variables Enumerations Pages
Public Member Functions | Friends | List of all members
hazelcast::client::IMap< K, V > Class Template Reference

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
listenerentry listener
includeValuetrue 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
listenerentry listener
keykey to listen
includeValuetrue 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
attributeattribute of value
orderedtrue 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
interceptormap 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
IClassCastExceptionif 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
IClassCastExceptionif 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
keyThe key of the map entry to remove.
Exceptions
IClassCastExceptionif 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
predicatequery 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
keykey 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
ResultTypethat entry processor will return
EntryProcessortype of entry processor class
Parameters
entryProcessorthat 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
EntryProcessortype of entry processor class
ResultTypethat entry processor will return
Parameters
entryProcessorthat will be applied
keyof 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
keykey 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
IClassCastExceptionif 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
keyskeys 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
keykey 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
keykey 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
predicatequery 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
keykey 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
keykey to lock.
leaseTimetime 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
IClassCastExceptionif 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
keykey of the entry
valuevalue of the entry
ttlInMillismaximum 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
mmappings 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
keykey 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
keykey of the entry
valuevalue of the entry
ttlInMillismaximum 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
keykey of the entry
valuevalue of the entry
ttlInMillismaximum 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
IClassCastExceptionif 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
IClassCastExceptionif 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
registrationIdid 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
idregistration 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
keykey with which the specified value is associated
oldValuevalue 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
keykey 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
keykey with which the specified value is associated
value
ttlmaximum 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
keykey 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
keykey to lock in this map
timeInMillismaximum 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
keykey of the entry
valuevalue of the entry
timeoutInMillismaximum 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
keykey of the entry
timeoutInMillismaximum 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
keykey to lock.
Exceptions
IllegalMonitorStateExceptionif 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
predicatethe 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: