K
- Cache key type.V
- Cache value type.public interface IgniteCache<K,V> extends javax.cache.Cache<K,V>, IgniteAsyncSupport
Ignite.jcache(String)
method.
CacheProjection
API which contains vast majority of cache functionality
and documentation. In addition to CacheProjection
functionality this API provides:
'loadCache(..)'
methods to load cache either synchronously or asynchronously.
These methods don't specify any keys to load, and leave it to the underlying storage to load cache
data based on the optionally passed in arguments.
'tx{Un}Synchronize(..)'
witch allow to get notifications for transaction state changes.
This feature is very useful when integrating cache transactions with some other in-house transactions.
metrics()
to provide metrics for the whole cache.getConfiguration(Class)
} to provide cache configuration bean.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,
javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
Object... arguments) |
<T> T |
invoke(K key,
IgniteEntryProcessor<K,V,T> entryProcessor,
Object... arguments)
Invokes an
IgniteEntryProcessor against the Entry specified by
the provided key. |
<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,
javax.cache.processor.EntryProcessor<K,V,T> entryProcessor,
Object... args) |
<T> Map<K,javax.cache.processor.EntryProcessorResult<T>> |
invokeAll(Set<? extends K> keys,
IgniteEntryProcessor<K,V,T> entryProcessor,
Object... args)
Invokes an
IgniteEntryProcessor against the set of Entry s
specified by the set of keys. |
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) |
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
GridCachePeekMode.SMART
peek mode. |
void |
localPromote(Set<? extends K> keys)
This method unswaps cache entries by given keys, if any, from swap storage
into memory.
|
QueryCursor<javax.cache.Cache.Entry<K,V>> |
localQuery(Query qry)
Queries cache locally.
|
QueryCursor<List<?>> |
localQueryFields(SqlFieldsQuery qry)
Queries separate entry fields locally.
|
int |
localSize(CachePeekMode... peekModes)
Gets the number of all entries cached on this nodes.
|
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) |
QueryCursor<javax.cache.Cache.Entry<K,V>> |
query(Query qry)
Queries cache.
|
QueryCursor<List<?>> |
queryFields(SqlFieldsQuery qry)
Queries separate entry fields.
|
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 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 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(Cache.Entry)
method.
CacheFlag.LOCAL
, CacheFlag.READ
.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.org.apache.ignite.internal.processors.cache.CacheFlagException
- If projection flags validation 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.QueryCursor<javax.cache.Cache.Entry<K,V>> query(Query qry)
Query
.QueryCursor<List<?>> queryFields(SqlFieldsQuery qry)
qry
- SQL Query.QueryCursor<javax.cache.Cache.Entry<K,V>> localQuery(Query qry)
Query
.QueryCursor<List<?>> localQueryFields(SqlFieldsQuery qry)
qry
- SQL Query.Iterable<javax.cache.Cache.Entry<K,V>> localEntries(CachePeekMode... peekModes) throws javax.cache.CacheException
javax.cache.CacheException
void localEvict(Collection<? extends K> keys)
If CacheConfiguration.isSwapEnabled()
is set to true
and
CacheFlag.SKIP_SWAP
is not enabled, the evicted entry will
be swapped to offheap, and then to disk.
CacheFlag.READ
.keys
- Keys to evict.V localPeek(K key, CachePeekMode... peekModes)
GridCachePeekMode.SMART
peek mode.
This method will not load value from any persistent store or from a remote node.
GridCachePeekMode.SMART
mode
semantics.key
- Entry key.null
if not found.NullPointerException
- If key is null
.void localPromote(Set<? extends K> keys) throws javax.cache.CacheException
CacheFlag.SKIP_SWAP
, CacheFlag.READ
.keys
- Keys to promote entries for.javax.cache.CacheException
- If promote failed.org.apache.ignite.internal.processors.cache.CacheFlagException
- If flags validation 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, IgniteEntryProcessor<K,V,T> entryProcessor, Object... arguments)
IgniteEntryProcessor
against the Entry
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.
This method different
key
- the key to the entryentryProcessor
- the IgniteEntryProcessor
to invokearguments
- additional arguments to pass to the
IgniteEntryProcessor
IgniteEntryProcessor
implementationNullPointerException
- if key or IgniteEntryProcessor
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 IgniteEntryProcessor
, a Caching Implementation
must wrap any Exception
thrown
wrapped in an EntryProcessorException
.IgniteEntryProcessor
@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, IgniteEntryProcessor<K,V,T> entryProcessor, Object... args)
IgniteEntryProcessor
against the set of Entry
s
specified by the 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 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 IgniteEntryProcessor
instance to process each entry, as
the case may be in a non-local cache topology.
The result of executing the IgniteEntryProcessor
is returned as a
Map
of EntryProcessorResult
s, one result per key. Should the
IgniteEntryProcessor
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 IgniteEntryProcessor
to invokeargs
- additional arguments to pass to the
IgniteEntryProcessor
EntryProcessorResult
s of the processing per key,
if any, defined by the IgniteEntryProcessor
implementation. No mappings
will be returned for IgniteEntryProcessor
s that return a
null
value for a key.NullPointerException
- if keys or IgniteEntryProcessor
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
IgniteEntryProcessor
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
CacheRendezvousAffinityFunction.setHashIdResolver(CacheAffinityNodeHashResolver)
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
Apache Ignite Fabric : ver. 1.0.0-RC3 Release Date : March 24 2015