This interface provides a rich API for working with distributed caches. It includes the following
main functionality:
-
Various
'get(..)' methods to synchronously or asynchronously get values from cache.
All
'get(..)' methods are transactional and will participate in an ongoing transaction
if there is one.
-
Various
'put(..)',
'putIfAbsent(..)', and
'replace(..)' methods to
synchronously or asynchronously put single or multiple entries into cache.
All these methods are transactional and will participate in an ongoing transaction
if there is one.
-
Various
'remove(..)' methods to synchronously or asynchronously remove single or multiple keys
from cache. All
'remove(..)' methods are transactional and will participate in an ongoing transaction
if there is one.
-
Various
'contains(..)' method to check if cache contains certain keys or values locally.
-
Various
'forEach(..)',
'forAny(..)', and
'reduce(..)' methods to visit
every local cache entry within this projection.
-
Various
flagsOn(..)',
'flagsOff(..)', and
'projection(..)' methods to
set specific flags and filters on a cache projection.
-
Methods like
'keySet(..)',
'values(..)', and
'entrySet(..)' to provide
views on cache keys, values, and entries.
-
Various
'peek(..)' methods to peek at values in global or transactional memory, swap
storage, or persistent storage.
-
Various
'reload(..)' methods to reload latest values from persistent storage.
-
Various
'promote(..)' methods to load specified keys from swap storage into
global cache memory.
-
Various
'lock(..)',
'unlock(..)', and
'isLocked(..)' methods to acquire, release,
and check on distributed locks on a single or multiple keys in cache. All locking methods
are not transactional and will not enlist keys into ongoing transaction, if any.
-
Various
'clear(..)' methods to clear elements from cache, and optionally from
swap storage. All
'clear(..)' methods are not transactional and will not enlist cleared
keys into ongoing transaction, if any.
-
Various
'evict(..)' methods to evict elements from cache, and optionally store
them in underlying swap storage for later access. All
'evict(..)' methods are not
transactional and will not enlist evicted keys into ongoing transaction, if any.
-
Various
'txStart(..)' methods to perform various cache
operations within a transaction (see
Transaction for more information).
-
Various
'gridProjection(..)' methods which provide
ClusterGroup only
for nodes on which given keys reside. All
'gridProjection(..)' methods are not
transactional and will not enlist keys into ongoing transaction.
-
Extended Put And Remove Methods
All methods that end with
'x' provide the same functionality as their sibling
methods that don't end with
'x', however instead of returning a previous value they
return a
boolean flag indicating whether operation succeeded or not. Returning
a previous value may involve a network trip or a persistent store lookup and should be
avoided whenever not needed.
Predicate Filters
All filters passed into methods on this API are checked
atomically. In other words the
value returned by the methods is guaranteed to be consistent with the filters passed in. Note
that filters are optional, and if not passed in, then methods will still work as is without
filter validation.
Transactions
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
Transaction documentation for more information
about transactions.
Group Locking
Group Locking is a feature where instead of acquiring individual locks, Ignite will lock
multiple keys with one lock to save on locking overhead. There are 2 types of
Group Locking:
affinity-based, and
partitioned-based.
With
affinity-based-group-locking the keys are grouped by affinity-key. This means that
only keys with identical affinity-key (see
AffinityKeyMapped) can participate in the
transaction, and only one lock on the affinity-key will be acquired for the whole transaction.
Affinity-group-locked transactions are started via
txStartAffinity(Object, TransactionConcurrency, TransactionIsolation, long, int)
method.
With
partition-based-group-locking the keys are grouped by partition ID. This means that
only keys belonging to identical partition (see
Affinity#partition(Object)) can participate in the
transaction, and only one lock on the whole partition will be acquired for the whole transaction.
Partition-group-locked transactions are started via
txStartPartition(int, TransactionConcurrency, TransactionIsolation, long, int)
method.
Group locking should always be used for transactions whenever possible. If your requirements fit either
affinity-based or partition-based scenarios outlined above then group-locking
can significantly improve performance of your application, often by an order of magnitude.
Null Keys or Values
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.
Peer Class Loading
If peer-class-loading is enabled, all classes passed into cache API will be automatically deployed
to any participating grid nodes. However, in case of redeployment, caches will be cleared and
all entries will be removed. This behavior is useful during development, but should not be
used in production.
Binary Objects
If an object is defined as binary Ignite cache will automatically store it in binary (i.e. binary)
format. User can choose to work either with the binary format or with the deserialized form (assuming
that class definitions are present in the classpath). By default, cache works with deserialized form
(example shows the case when
Integer is used as a key for a binary object):
IgniteInternalCache prj = Ignition.grid().cache(null);
// Value will be serialized and stored in cache in binary format.
prj.put(1, new Value());
// Value will be deserialized since it's stored in binary format.
Value val = prj.get(1);
You won't be able to work with deserialized form if class definition for the
Value is not on
classpath. Even if you have the class definition, you should always avoid full deserialization if it's not
needed for performance reasons. To work with binary format directly you should create special projection
using
#keepBinary() method:
IgniteInternalCache prj = Ignition.grid().cache(null).keepBinary();
// Value is not deserialized and returned in binary format.
GridBinaryObject po = prj.get(1);
See
#keepBinary() method JavaDoc for more details.