K
- Cache key type.V
- Cache value type.public interface IgniteCache<K,V> extends javax.cache.Cache<K,V>, IgniteAsyncSupport
Ignite.cache(String)
method.
Cache
API which contains JCache (JSR107)
cache functionality
and documentation. In addition to Cache
functionality this API provides:
JCache
API.loadCache(IgniteBiPredicate, Object...)
method.
lock(Object)
methods.query(Query)
method.rebalance()
methopd
(in case if delayed rebalancing was configured.)get(...)
from cache
via localPeek(Object, CachePeekMode...)
methodsinvoke(Object, CacheEntryProcessor, Object...)
methods.IgniteTransactions
for more information.
IgniteAsyncSupport
functionality. To turn on
asynchronous mode invoke withAsync()
method. Once asynchronous mode is enabled,
all methods with @IgniteAsyncSupported
annotation will be executed
asynchronously.Modifier and Type | Method and Description |
---|---|
void |
clear() |
void |
clear(K key)
Clear entry from the cache and swap storage, without notifying listeners or
CacheWriter s. |
void |
clearAll(Set<K> keys)
Clear entries from the cache and swap storage, without notifying listeners or
CacheWriter s. |
boolean |
containsKey(K key) |
boolean |
containsKeys(Set<? extends K> keys) |
V |
get(K key) |
Map<K,V> |
getAll(Set<? extends K> keys) |
V |
getAndPut(K key,
V val) |
V |
getAndPutIfAbsent(K key,
V val)
Stores given key-value pair in cache only if cache had no previous mapping for it.
|
V |
getAndRemove(K key) |
V |
getAndReplace(K key,
V val) |
<C extends javax.cache.configuration.Configuration<K,V>> |
getConfiguration(Class<C> clazz) |
<T> T |
invoke(K key,
CacheEntryProcessor<K,V,T> entryProcessor,
Object... arguments)
Invokes an
CacheEntryProcessor against the Cache.Entry specified by
the provided key. |
<T> T |
invoke(K key,
javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
Object... arguments) |
<T> Map<K,javax.cache.processor.EntryProcessorResult<T>> |
invokeAll(Map<? extends K,? extends javax.cache.processor.EntryProcessor<K,V,T>> map,
Object... args) |
<T> Map<K,javax.cache.processor.EntryProcessorResult<T>> |
invokeAll(Set<? extends K> keys,
CacheEntryProcessor<K,V,T> entryProcessor,
Object... args)
Invokes an
CacheEntryProcessor against the set of Cache.Entry s
specified by the set of keys. |
<T> Map<K,javax.cache.processor.EntryProcessorResult<T>> |
invokeAll(Set<? extends K> keys,
javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
Object... args) |
boolean |
isLocalLocked(K key,
boolean byCurrThread)
Checks if specified key is locked.
|
void |
loadCache(IgniteBiPredicate<K,V> p,
Object... args)
Executes
localLoadCache(IgniteBiPredicate, Object...) on all cache nodes. |
void |
localClear(K key)
Clear entry from the cache and swap storage, without notifying listeners or
CacheWriter s. |
void |
localClearAll(Set<K> keys)
Clear entries from the cache and swap storage, without notifying listeners or
CacheWriter s. |
Iterable<javax.cache.Cache.Entry<K,V>> |
localEntries(CachePeekMode... peekModes)
Allows for iteration over local cache entries.
|
void |
localEvict(Collection<? extends K> keys)
Attempts to evict all entries associated with keys.
|
void |
localLoadCache(IgniteBiPredicate<K,V> p,
Object... args)
Delegates to
CacheStore.loadCache(IgniteBiInClosure,Object...) method
to load state from the underlying persistent storage. |
V |
localPeek(K key,
CachePeekMode... peekModes)
Peeks at in-memory cached value using default optinal peek mode.
|
void |
localPromote(Set<? extends K> keys)
This method unswaps cache entries by given keys, if any, from swap storage
into memory.
|
int |
localSize(CachePeekMode... peekModes)
Gets the number of all entries cached on this node.
|
Lock |
lock(K key)
Creates a
Lock instance associated with passed key. |
Lock |
lockAll(Collection<? extends K> keys)
Creates a
Lock instance associated with passed keys. |
CacheMetrics |
metrics()
Gets snapshot metrics (statistics) for this cache.
|
CacheMetricsMXBean |
mxBean()
Gets MxBean for this cache.
|
void |
put(K key,
V val) |
void |
putAll(Map<? extends K,? extends V> map) |
boolean |
putIfAbsent(K key,
V val) |
<R> QueryCursor<R> |
query(Query<R> qry)
Queries cache.
|
QueryMetrics |
queryMetrics()
Gets query metrics.
|
javax.cache.Cache.Entry<K,V> |
randomEntry()
Gets a random entry out of cache.
|
IgniteFuture<?> |
rebalance()
This cache node to re-balance its partitions.
|
boolean |
remove(K key) |
boolean |
remove(K key,
V oldVal) |
void |
removeAll() |
void |
removeAll(Set<? extends K> keys) |
boolean |
replace(K key,
V val) |
boolean |
replace(K key,
V oldVal,
V newVal) |
int |
size(CachePeekMode... peekModes)
Gets the number of all entries cached across all nodes.
|
IgniteCache<K,V> |
withAsync()
Gets component with asynchronous mode enabled.
|
IgniteCache<K,V> |
withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc) |
IgniteCache<K,V> |
withSkipStore() |
close, deregisterCacheEntryListener, getCacheManager, getName, isClosed, iterator, loadAll, registerCacheEntryListener, unwrap
future, isAsync
IgniteCache<K,V> withAsync()
withAsync
in interface IgniteAsyncSupport
<C extends javax.cache.configuration.Configuration<K,V>> C getConfiguration(Class<C> clazz)
javax.cache.Cache.Entry<K,V> randomEntry()
O(S * N/64)where
N
is the size of internal hash
table and S
is the number of hash table buckets to sample, which is 5
by default. However, if the table is pretty dense, with density factor of N/64
,
which is true for near fully populated caches, this method will generally perform significantly
faster with complexity of O(S) where S = 5
.null
if cache is empty.IgniteCache<K,V> withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc)
IgniteCache<K,V> withSkipStore()
@IgniteAsyncSupported void loadCache(@Nullable IgniteBiPredicate<K,V> p, @Nullable Object... args) throws javax.cache.CacheException
localLoadCache(IgniteBiPredicate, Object...)
on all cache nodes.p
- Optional predicate (may be null
). If provided, will be used to
filter values loaded from storage before they are put into cache.args
- Optional user arguments to be passed into
CacheStore.loadCache(IgniteBiInClosure, Object...)
method.javax.cache.CacheException
- If loading failed.@IgniteAsyncSupported void localLoadCache(@Nullable IgniteBiPredicate<K,V> p, @Nullable Object... args) throws javax.cache.CacheException
CacheStore.loadCache(IgniteBiInClosure,Object...)
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.
Note that this method does not receive keys as a parameter, so it is up to
CacheStore
implementation to provide all the data to be loaded.
This method is not transactional and may end up loading a stale value into cache if another thread has updated the value immediately after it has been loaded. It is mostly useful when pre-loading the cache from underlying data store before start, or for read-only caches.
p
- Optional predicate (may be null
). If provided, will be used to
filter values to be put into cache.args
- Optional user arguments to be passed into
CacheStore.loadCache(IgniteBiInClosure, Object...)
method.javax.cache.CacheException
- If loading failed.@IgniteAsyncSupported V getAndPutIfAbsent(K key, V val) throws javax.cache.CacheException
CacheMode.PARTITIONED
or CacheMode.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 value has to be loaded from persistent
storage, CacheLoader.load(Object)
method will be used.
If the returned value is not needed, method putIfAbsent(Object, Object)
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 stored value will be persisted to CacheStore
via CacheWriter.write(javax.cache.Cache.Entry)
method.
key
- Key to store in cache.val
- Value to be associated with the given key.null
if there was no
previous value).NullPointerException
- If either key or value are null
.javax.cache.CacheException
- If put operation failed.Lock lock(K key)
Lock
instance associated with passed key.
This method does not acquire lock immediately, you have to call appropriate method on returned instance.
Returned lock does not support Lock.newCondition()
method,
other methods defined in Lock
are supported.key
- Key for lock.Lock.lock()
,
Lock.tryLock(long, TimeUnit)
Lock lockAll(Collection<? extends K> keys)
Lock
instance associated with passed keys.
This method does not acquire lock immediately, you have to call appropriate method on returned instance.
Returned lock does not support Lock.newCondition()
method,
other methods defined in Lock
are supported.keys
- Keys for lock.Lock.lock()
,
Lock.tryLock(long, TimeUnit)
boolean isLocalLocked(K key, boolean byCurrThread)
This is a local in-VM operation and does not involve any network trips or access to persistent storage in any way.
key
- Key to check.byCurrThread
- If true
method will check that current thread owns a lock on this key, other vise
will check that any thread on any node owns a lock on this key.True
if lock is owned by some node.<R> QueryCursor<R> query(Query<R> qry)
Query
interface.Iterable<javax.cache.Cache.Entry<K,V>> localEntries(CachePeekMode... peekModes) throws javax.cache.CacheException
peekModes
- Peek modes.javax.cache.CacheException
- If failed.QueryMetrics queryMetrics()
void localEvict(Collection<? extends K> keys)
keys
- Keys to evict.V localPeek(K key, CachePeekMode... peekModes)
This method will not load value from any persistent store or from a remote node.
key
- Entry key.null
if not found.NullPointerException
- If key is null
.void localPromote(Set<? extends K> keys) throws javax.cache.CacheException
keys
- Keys to promote entries for.javax.cache.CacheException
- If promote failed.@IgniteAsyncSupported int size(CachePeekMode... peekModes) throws javax.cache.CacheException
NOTE: this operation is distributed and will query all participating nodes for their cache sizes.
peekModes
- Optional peek modes. If not provided, then total cache size is returned.javax.cache.CacheException
int localSize(CachePeekMode... peekModes)
peekModes
- Optional peek modes. If not provided, then total cache size is returned.@IgniteAsyncSupported <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Map<? extends K,? extends javax.cache.processor.EntryProcessor<K,V,T>> map, Object... args)
map
- Map containing keys and entry processors to be applied to values.args
- Additional arguments to pass to the EntryProcessor
.EntryProcessorResult
s of the processing per key,
if any, defined by the EntryProcessor
implementation. No mappings
will be returned for EntryProcessor
s that return a
null
value for a key.@IgniteAsyncSupported V get(K key)
@IgniteAsyncSupported boolean containsKey(K key)
@IgniteAsyncSupported boolean containsKeys(Set<? extends K> keys)
@IgniteAsyncSupported void put(K key, V val)
@IgniteAsyncSupported V getAndPut(K key, V val)
@IgniteAsyncSupported void putAll(Map<? extends K,? extends V> map)
@IgniteAsyncSupported boolean putIfAbsent(K key, V val)
@IgniteAsyncSupported boolean remove(K key)
@IgniteAsyncSupported boolean remove(K key, V oldVal)
@IgniteAsyncSupported V getAndRemove(K key)
@IgniteAsyncSupported boolean replace(K key, V oldVal, V newVal)
@IgniteAsyncSupported boolean replace(K key, V val)
@IgniteAsyncSupported V getAndReplace(K key, V val)
@IgniteAsyncSupported void removeAll(Set<? extends K> keys)
@IgniteAsyncSupported void removeAll()
@IgniteAsyncSupported void clear()
@IgniteAsyncSupported void clear(K key)
CacheWriter
s. Entry is cleared only if it is not currently locked,
and is not participating in a transaction.key
- Key to clear.IllegalStateException
- if the cache is Cache.isClosed()
javax.cache.CacheException
- if there is a problem during the clear@IgniteAsyncSupported void clearAll(Set<K> keys)
CacheWriter
s. Entry is cleared only if it is not currently locked,
and is not participating in a transaction.keys
- Keys to clear.IllegalStateException
- if the cache is Cache.isClosed()
javax.cache.CacheException
- if there is a problem during the clearvoid localClear(K key)
CacheWriter
s. Entry is cleared only if it is not currently locked,
and is not participating in a transaction.
Note that this operation is local as it merely clears
an entry from local cache, it does not remove entries from
remote caches.key
- Key to clear.void localClearAll(Set<K> keys)
CacheWriter
s. Entry is cleared only if it is not currently locked,
and is not participating in a transaction.
Note that this operation is local as it merely clears
an entry from local cache, it does not remove entries from
remote caches.keys
- Keys to clear.@IgniteAsyncSupported <T> T invoke(K key, javax.cache.processor.EntryProcessor<K,V,T> entryProcessor, Object... arguments)
@IgniteAsyncSupported <T> T invoke(K key, CacheEntryProcessor<K,V,T> entryProcessor, Object... arguments)
CacheEntryProcessor
against the Cache.Entry
specified by
the provided key. If an Cache.Entry
does not exist for the specified key,
an attempt is made to load it (if a loader is configured) or a surrogate
Cache.Entry
, consisting of the key with a null value is used instead.
This method different
key
- the key to the entryentryProcessor
- the CacheEntryProcessor
to invokearguments
- additional arguments to pass to the
CacheEntryProcessor
CacheEntryProcessor
implementationNullPointerException
- if key or CacheEntryProcessor
is nullIllegalStateException
- if the cache is Cache.isClosed()
ClassCastException
- if the implementation is configured to perform
runtime-type-checking, and the key or value
types are incompatible with those that have been
configured for the Cache
javax.cache.processor.EntryProcessorException
- if an exception is thrown by the CacheEntryProcessor
, a Caching Implementation
must wrap any Exception
thrown
wrapped in an EntryProcessorException
.CacheEntryProcessor
@IgniteAsyncSupported <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, javax.cache.processor.EntryProcessor<K,V,T> entryProcessor, Object... args)
@IgniteAsyncSupported <T> Map<K,javax.cache.processor.EntryProcessorResult<T>> invokeAll(Set<? extends K> keys, CacheEntryProcessor<K,V,T> entryProcessor, Object... args)
CacheEntryProcessor
against the set of Cache.Entry
s
specified by the set of keys.
If an Cache.Entry
does not exist for the specified key, an attempt is made
to load it (if a loader is configured) or a surrogate Cache.Entry
,
consisting of the key and a value of null is provided.
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 CacheEntryProcessor
instance to process each entry, as
the case may be in a non-local cache topology.
The result of executing the CacheEntryProcessor
is returned as a
Map
of EntryProcessorResult
s, one result per key. Should the
CacheEntryProcessor
or Caching implementation throw an exception, the
exception is wrapped and re-thrown when a call to
EntryProcessorResult.get()
is made.
keys
- the set of keys for entries to processentryProcessor
- the CacheEntryProcessor
to invokeargs
- additional arguments to pass to the
CacheEntryProcessor
EntryProcessorResult
s of the processing per key,
if any, defined by the CacheEntryProcessor
implementation. No mappings
will be returned for CacheEntryProcessor
s that return a
null
value for a key.NullPointerException
- if keys or CacheEntryProcessor
are nullIllegalStateException
- if the cache is Cache.isClosed()
ClassCastException
- if the implementation is configured to perform
runtime-type-checking, and the key or value
types are incompatible with those that have been
configured for the Cache
CacheEntryProcessor
IgniteFuture<?> rebalance()
CacheConfiguration.getRebalanceDelay()
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.
In case ofCacheMode.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. To place nodes
on the same place in consistent hash ring, use
RendezvousAffinityFunction.setHashIdResolver(AffinityNodeHashResolver)
to make sure that
a node maps to the same hash ID if re-started.
See CacheConfiguration.getRebalanceDelay()
for more information on how to configure
rebalance re-partition delay.
CacheMetrics metrics()
CacheMetricsMXBean mxBean()
Follow @ApacheIgnite
Ignite Fabric : ver. 1.0.0 Release Date : March 31 2015