Public Member Functions | Properties | List of all members
GridGain.Cache.ICache< K, V > Interface Template Reference

Main entry point for all Data Grid APIs. You can get a named cache by calling GridGain.IGrid.Cache<K, V>(string) method. More...

Inherits IAsyncSupport< ICache< K, V >>, and IEnumerable< ICacheEntry< K, V >>.

Public Member Functions

ICache< K, V > WithSkipStore ()
 Get another cache instance with read-through and write-through behavior disabled. More...
 
ICache< K, V > WithExpiryPolicy (IExpiryPolicy plc)
 Returns cache with the specified expired policy set. This policy will be used for each operation invoked on the returned cache. More...
 
ICache< K1, V1 > WithKeepPortable< K1, V1 > ()
 Gets cache with KeepPortable mode enabled, changing key and/or value types if necessary. You can only change key/value types when transitioning from non-portable to portable cache; Changing type of portable cache is not allowed and will throw an InvalidOperationException More...
 
void LoadCache (ICacheEntryFilter< K, V > p, params object[] args)
 Executes LocalLoadCache on all cache nodes. More...
 
void LocalLoadCache (ICacheEntryFilter< K, V > p, params object[] args)
 Delegates to ICacheStore.LoadCache method to load state from the underlying persistent storage. The loaded values will then be given to the optionally passed in predicate, and, if the predicate returns true, will be stored in cache. If predicate is null, then all loaded values will be stored in cache. More...
 
bool ContainsKey (K key)
 Check if cache contains mapping for this key. More...
 
bool ContainsKeys (IEnumerable< K > keys)
 Check if cache contains mapping for these keys. More...
 
V LocalPeek (K key, params CachePeekMode[] modes)
 Peeks at cached value using optional set of peek modes. This method will sequentially iterate over given peek modes, and try to peek at value using each peek mode. Once a non-null value is found, it will be immediately returned. This method does not participate in any transactions, however, it may peek at transactional value depending on the peek modes used. More...
 
V Get (K key)
 Retrieves value mapped to the specified key from cache. If the value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disable, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
IDictionary< K, V > GetAll (IEnumerable< K > keys)
 Retrieves values mapped to the specified keys from cache. If some value is not present in cache, then it will be looked up from swap storage. If it's not present in swap, or if swap is disabled, and if read-through is allowed, value will be loaded from persistent store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
void Put (K key, V val)
 Associates the specified value with the specified key in the cache. More...
 
V GetAndPut (K key, V val)
 Associates the specified value with the specified key in this cache, returning an existing value if one existed. More...
 
V GetAndReplace (K key, V val)
 Atomically replaces the value for a given key if and only if there is a value currently mapped by the key. More...
 
V GetAndRemove (K key)
 Atomically removes the entry for a key only if currently mapped to some value. More...
 
bool PutIfAbsent (K key, V val)
 Atomically associates the specified key with the given value if it is not already associated with a value. More...
 
V GetAndPutIfAbsent (K key, V val)
 Stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method putxIfAbsent() should be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
bool Replace (K key, V val)
 Stores given key-value pair in cache only if there is a previous mapping for it. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the swap storage, and consecutively, if it's not in swap, rom the underlying persistent storage. If write-through is enabled, the stored value will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
bool Replace (K key, V oldVal, V newVal)
 Stores given key-value pair in cache only if only if the previous value is equal to the old value passed as argument. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
void PutAll (IDictionary< K, V > vals)
 Stores given key-value pairs in cache. If write-through is enabled, the stored values will be persisted to store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
void LocalEvict (IEnumerable< K > keys)
 Attempts to evict all entries associated with keys. Note, that entry will be evicted only if it's not used (not participating in any locks or transactions). More...
 
void Clear ()
 Clears the contents of the cache, without notifying listeners or CacheWriters. More...
 
void Clear (K key)
 Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction. More...
 
void ClearAll (IEnumerable< K > keys)
 Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction. More...
 
void LocalClear (K key)
 Clear entry from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction. More...
 
void LocalClearAll (IEnumerable< K > keys)
 Clear entries from the cache and swap storage, without notifying listeners or CacheWriters. Entry is cleared only if it is not currently locked, and is not participating in a transaction. More...
 
bool Remove (K key)
 Removes given key mapping from cache. If cache previously contained value for the given key, then this value is returned. In case of PARTITIONED or REPLICATED caches, the value will be loaded from the primary node, which in its turn may load the value from the disk-based swap storage, and consecutively, if it's not in swap, from the underlying persistent storage. If the returned value is not needed, method removex() should always be used instead of this one to avoid the overhead associated with returning of the previous value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
bool Remove (K key, V val)
 Removes given key mapping from cache if one exists and value is equal to the passed in value. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
void RemoveAll (IEnumerable< K > keys)
 Removes given key mappings from cache. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
void RemoveAll ()
 Removes all mappings from cache. If write-through is enabled, the value will be removed from store. This method is transactional and will enlist the entry into ongoing transaction if there is one. More...
 
int LocalSize (params CachePeekMode[] modes)
 Gets the number of all entries cached on this node. More...
 
int Size (params CachePeekMode[] modes)
 Gets the number of all entries cached across all nodes. More...
 
void LocalPromote (IEnumerable< K > keys)
 This method unswaps cache entries by given keys, if any, from swap storage into memory. More...
 
IQueryCursor< ICacheEntry< K, V > > Query (QueryBase qry)
 Queries cache. More...
 
IQueryCursor< IList > QueryFields (SqlFieldsQuery qry)
 Queries separate entry fields. More...
 
IContinuousQueryHandle QueryContinuous (ContinuousQuery< K, V > qry)
 Start continuous query execution. More...
 
IContinuousQueryHandle< ICacheEntry< K, V > > QueryContinuous (ContinuousQuery< K, V > qry, QueryBase initialQry)
 Start continuous query execution. More...
 
IEnumerable< ICacheEntry< K, V > > GetLocalEntries (params CachePeekMode[] peekModes)
 Get local cache entries. More...
 
R Invoke< R, A > (K key, ICacheEntryProcessor< K, V, A, R > processor, A arg)
 Invokes an ICacheEntryProcessor<K, V, A, R> against the IMutableCacheEntry<K, V> specified by the provided key. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead. More...
 
IDictionary< K, ICacheEntryProcessorResult< R > > InvokeAll< R, A > (IEnumerable< K > keys, ICacheEntryProcessor< K, V, A, R > processor, A arg)
 Invokes an ICacheEntryProcessor<K, V, A, R> against a set of keys. If an entry does not exist for the specified key, an attempt is made to load it (if a loader is configured) or a surrogate entry, consisting of the key with a null value is used instead. More...
 
ICacheLock Lock (K key)
 Creates an ICacheLock instance associated with passed key. This method does not acquire lock immediately, you have to call appropriate method on returned instance. More...
 
ICacheLock LockAll (IEnumerable< K > keys)
 Creates an ICacheLock instance associated with passed keys. This method does not acquire lock immediately, you have to call appropriate method on returned instance. More...
 
bool IsLocalLocked (K key, bool byCurrentThread)
 Checks if specified key is locked. More...
 
ICacheMetrics GetMetrics ()
 Gets snapshot metrics (statistics) for this cache. More...
 
IFuture Rebalance ()
 Rebalances cache partitions. This method is usually used when rebalanceDelay configuration parameter has non-zero value. When many nodes are started or stopped almost concurrently, it is more efficient to delay rebalancing until the node topology is stable to make sure that no redundant re-partitioning happens. More...
 
ICache< K, V > WithNoRetries ()
 Get another cache instance with no-retries behavior enabled. More...
 

Properties

string Name [get]
 Name of this cache (null for default cache). More...
 
IGrid Grid [get]
 Grid hosting this cache. More...
 
bool IsEmpty [get]
 Checks whether this cache contains no key-value mappings. More...
 
bool KeepPortable [get]
 Gets a value indicating whether to keep values in portable form. More...
 

Detailed Description

Cache API supports distributed transactions. All Get(...), Put(...), Replace(...), and Remove(...) operations are transactional and will participate in an ongoing transaction, if any. Other methods like Peek(...) or various Contains(...) methods may be transaction-aware, i.e. check in-transaction entries first, but will not affect the current state of transaction. See ITransaction documentation for more information about transactions.

Neither null keys or values are allowed to be stored in cache. If a null value happens to be in cache (e.g. after invalidation or remove), then cache will treat this case as there is no value at all.

Note that cache is generic and you can only work with provided key and value types. If cache also contains keys or values of other types, any attempt to retrieve them will result in InvalidCastException. Use ICache<Object, Object> in order to work with entries of arbitrary types.

All members are thread-safe and may be used concurrently from multiple threads.

Template Parameters
KKey type.
VValue type.

Member Function Documentation

void GridGain.Cache.ICache< K, V >.Clear ( )
void GridGain.Cache.ICache< K, V >.Clear ( K  key)
Parameters
keyKey to clear.
void GridGain.Cache.ICache< K, V >.ClearAll ( IEnumerable< K >  keys)
Parameters
keysKeys to clear.
bool GridGain.Cache.ICache< K, V >.ContainsKey ( K  key)
Parameters
keyKey.
Returns
True if cache contains mapping for this key.
bool GridGain.Cache.ICache< K, V >.ContainsKeys ( IEnumerable< K >  keys)
Parameters
keysKeys.
Returns
True if cache contains mapping for all these keys.
V GridGain.Cache.ICache< K, V >.Get ( K  key)
Parameters
keyKey.
Returns
Value.
IDictionary<K, V> GridGain.Cache.ICache< K, V >.GetAll ( IEnumerable< K >  keys)
Parameters
keysKeys.
Returns
Map of key-value pairs.
V GridGain.Cache.ICache< K, V >.GetAndPut ( K  key,
V  val 
)
Parameters
keyKey with which the specified value is to be associated.
valValue to be associated with the specified key.
Returns
The value associated with the key at the start of the operation or null if none was associated.
V GridGain.Cache.ICache< K, V >.GetAndPutIfAbsent ( K  key,
V  val 
)
Parameters
keyKey to store in cache.
valValue to be associated with the given key.
Returns
Previously contained value regardless of whether put happened or not (null if there was no previous value).
V GridGain.Cache.ICache< K, V >.GetAndRemove ( K  key)
Parameters
keyKey with which the specified value is associated.
Returns
The value if one existed or null if no mapping existed for this key.
V GridGain.Cache.ICache< K, V >.GetAndReplace ( K  key,
V  val 
)
Parameters
keyKey with which the specified value is to be associated.
valValue to be associated with the specified key.
Returns
The previous value associated with the specified key, or null if there was no mapping for the key.
IEnumerable<ICacheEntry<K, V> > GridGain.Cache.ICache< K, V >.GetLocalEntries ( params CachePeekMode[]  peekModes)
Parameters
peekModesPeek modes.
Returns
Enumerable instance.
ICacheMetrics GridGain.Cache.ICache< K, V >.GetMetrics ( )
Returns
Cache metrics.
R GridGain.Cache.ICache< K, V >.Invoke< R, A > ( K  key,
ICacheEntryProcessor< K, V, A, R >  processor,
A  arg 
)
Template Parameters
RThe type of the result.
AThe type of the argument.
Parameters
keyThe key.
processorThe processor.
argThe argument.
Returns
Result of the processing.
Exceptions
CacheEntryProcessorExceptionIf an exception has occured during processing.
IDictionary<K, ICacheEntryProcessorResult<R> > GridGain.Cache.ICache< K, V >.InvokeAll< R, A > ( IEnumerable< K >  keys,
ICacheEntryProcessor< K, V, A, R >  processor,
A  arg 
)

The order that the entries for the keys are processed is undefined. Implementations may choose to process the entries in any order, including concurrently. Furthermore there is no guarantee implementations will use the same processor instance to process each entry, as the case may be in a non-local cache topology.

Template Parameters
RThe type of the result.
AThe type of the argument.
Parameters
keysThe keys.
processorThe processor.
argThe argument.
Returns
Map of ICacheEntryProcessorResult<R> of the processing per key, if any, defined by the ICacheEntryProcessor<K,V,A,R> implementation. No mappings will be returned for processors that return a null value for a key.
Exceptions
CacheEntryProcessorExceptionIf an exception has occured during processing.
bool GridGain.Cache.ICache< K, V >.IsLocalLocked ( K  key,
bool  byCurrentThread 
)

This is a local operation and does not involve any network trips or access to persistent storage in any way.

Parameters
keyKey to check.
byCurrentThreadIf true, checks that current thread owns a lock on this key; otherwise, checks that any thread on any node owns a lock on this key.
Returns
True if specified key is locked; otherwise, false.
void GridGain.Cache.ICache< K, V >.LoadCache ( ICacheEntryFilter< K, V >  p,
params object[]  args 
)
Parameters
pOptional predicate. If provided, will be used to filter values to be put into cache.
argsOptional user arguments to be passed into ICacheStore.LoadCache.
void GridGain.Cache.ICache< K, V >.LocalClear ( K  key)

Note that this operation is local as it merely clears an entry from local cache, it does not remove entries from remote caches.

Parameters
keyKey to clear.
void GridGain.Cache.ICache< K, V >.LocalClearAll ( IEnumerable< K >  keys)

Note that this operation is local as it merely clears entries from local cache, it does not remove entries from remote caches.

Parameters
keysKeys to clear.
void GridGain.Cache.ICache< K, V >.LocalEvict ( IEnumerable< K >  keys)
Parameters
keysKeys to evict from cache.
void GridGain.Cache.ICache< K, V >.LocalLoadCache ( ICacheEntryFilter< K, V >  p,
params object[]  args 
)
Parameters
pOptional predicate. If provided, will be used to filter values to be put into cache.
argsOptional user arguments to be passed into ICacheStore.LoadCache.
V GridGain.Cache.ICache< K, V >.LocalPeek ( K  key,
params CachePeekMode[]  modes 
)
Parameters
keyKey.
modesPeek modes.
Returns
Peeked value.
void GridGain.Cache.ICache< K, V >.LocalPromote ( IEnumerable< K >  keys)
Parameters
keysKeys to promote entries for.
int GridGain.Cache.ICache< K, V >.LocalSize ( params CachePeekMode[]  modes)
Parameters
modesOptional peek modes. If not provided, then total cache size is returned.
Returns
Cache size on this node.
ICacheLock GridGain.Cache.ICache< K, V >.Lock ( K  key)
Parameters
keyKey for lock.
Returns
New ICacheLock instance associated with passed key.
ICacheLock GridGain.Cache.ICache< K, V >.LockAll ( IEnumerable< K >  keys)
Parameters
keysKeys for lock.
Returns
New ICacheLock instance associated with passed keys.
void GridGain.Cache.ICache< K, V >.Put ( K  key,
V  val 
)

If the cache previously contained a mapping for the key, the old value is replaced by the specified value.

Parameters
keyKey with which the specified value is to be associated.
valValue to be associated with the specified key.
void GridGain.Cache.ICache< K, V >.PutAll ( IDictionary< K, V >  vals)
Parameters
valsKey-value pairs to store in cache.
bool GridGain.Cache.ICache< K, V >.PutIfAbsent ( K  key,
V  val 
)
Parameters
keyKey with which the specified value is to be associated.
valValue to be associated with the specified key.
Returns
True if a value was set.
IQueryCursor<ICacheEntry<K, V> > GridGain.Cache.ICache< K, V >.Query ( QueryBase  qry)
Parameters
qryQuery.
Returns
Cursor.
IContinuousQueryHandle GridGain.Cache.ICache< K, V >.QueryContinuous ( ContinuousQuery< K, V >  qry)
Parameters
qryContinuous query.
Returns
Handle to stop query execution.
IContinuousQueryHandle<ICacheEntry<K, V> > GridGain.Cache.ICache< K, V >.QueryContinuous ( ContinuousQuery< K, V >  qry,
QueryBase  initialQry 
)
Parameters
qryContinuous query.
initialQryThe initial query. This query will be executed before continuous listener is registered which allows to iterate through entries which have already existed at the time continuous query is executed.
Returns
Handle to get initial query cursor or stop query execution.
IQueryCursor<IList> GridGain.Cache.ICache< K, V >.QueryFields ( SqlFieldsQuery  qry)
Parameters
qrySQL fields query.
Returns
Cursor.
IFuture GridGain.Cache.ICache< K, V >.Rebalance ( )

In case of partitioned caches, for better efficiency user should usually make sure that new nodes get placed on the same place of consistent hash ring as the left nodes, and that nodes are restarted before rebalanceDelay expires.

Returns
Future that will be completed when rebalancing is finished.
bool GridGain.Cache.ICache< K, V >.Remove ( K  key)
Parameters
keyKey whose mapping is to be removed from cache.
Returns
False if there was no matching key.
bool GridGain.Cache.ICache< K, V >.Remove ( K  key,
V  val 
)
Parameters
keyKey whose mapping is to be removed from cache.
valValue to match against currently cached value.
Returns
True if entry was removed, false otherwise.
void GridGain.Cache.ICache< K, V >.RemoveAll ( IEnumerable< K >  keys)
Parameters
keysKeys whose mappings are to be removed from cache.
void GridGain.Cache.ICache< K, V >.RemoveAll ( )
bool GridGain.Cache.ICache< K, V >.Replace ( K  key,
V  val 
)
Parameters
keyKey to store in cache.
valValue to be associated with the given key.
Returns
True if the value was replaced.
bool GridGain.Cache.ICache< K, V >.Replace ( K  key,
V  oldVal,
V  newVal 
)
Parameters
keyKey to store in cache.
oldValOld value to match.
newValValue to be associated with the given key.
Returns
True if replace happened, false otherwise.
int GridGain.Cache.ICache< K, V >.Size ( params CachePeekMode[]  modes)

NOTE: this operation is distributed and will query all participating nodes for their cache sizes.

Parameters
modesOptional peek modes. If not provided, then total cache size is returned.
Returns
Cache size across all nodes.
ICache<K, V> GridGain.Cache.ICache< K, V >.WithExpiryPolicy ( IExpiryPolicy  plc)

Expiry durations for each operation are calculated only once and then used as constants. Please consider this when implementing customg expiry policy implementations.

Parameters
plcExpiry policy to use.
Returns
Cache instance with the specified expiry policy set.
ICache<K1, V1> GridGain.Cache.ICache< K, V >.WithKeepPortable< K1, V1 > ( )
Template Parameters
K1Key type in portable mode.
V1Value type in protable mode.
Returns
Cache instance with portable mode enabled.
ICache<K, V> GridGain.Cache.ICache< K, V >.WithNoRetries ( )
Returns
Cache with no-retries behavior enabled.
ICache<K, V> GridGain.Cache.ICache< K, V >.WithSkipStore ( )
Returns
Cache with read-through and write-through behavior disabled.

Property Documentation

IGrid GridGain.Cache.ICache< K, V >.Grid
get
bool GridGain.Cache.ICache< K, V >.IsEmpty
get

Semantically equals to ICache.Size(CachePeekMode.PRIMARY) == 0.

bool GridGain.Cache.ICache< K, V >.KeepPortable
get
string GridGain.Cache.ICache< K, V >.Name
get