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
CacheWriters. |
void |
clearAll(Set<? extends K> keys)
Clear entries from the cache and swap storage, without notifying listeners or
CacheWriters. |
void |
close()
Closes this cache instance.
|
boolean |
containsKey(K key) |
boolean |
containsKeys(Set<? extends K> keys)
Determines if the
Cache contains entries for the specified keys. |
void |
destroy()
Completely deletes the cache with all its data from the system on all cluster nodes.
|
V |
get(K key) |
Map<K,V> |
getAll(Set<? extends K> keys) |
Map<K,V> |
getAllOutTx(Set<? extends K> keys)
Gets values from cache.
|
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) |
Collection<CacheEntry<K,V>> |
getEntries(Set<? extends K> keys)
Gets a collection of entries from the
Cache. |
CacheEntry<K,V> |
getEntry(K key)
Gets an entry from the cache.
|
<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.Entrys
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
CacheWriters. |
void |
localClearAll(Set<? extends K> keys)
Clear entries from the cache and swap storage, without notifying listeners or
CacheWriters. |
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.
|
long |
localSizeLong(CachePeekMode... peekModes)
Gets the number of all entries cached on this node as a long value.
|
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.
|
CacheMetrics |
metrics(ClusterGroup grp)
Gets snapshot metrics for caches in cluster group.
|
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()
Deprecated.
|
IgniteFuture<?> |
rebalance()
This cache node to re-balance its partitions.
|
boolean |
remove(K key) |
boolean |
remove(K key,
V oldVal) |
void |
removeAll()
Removes all of the mappings from this cache.
|
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.
|
long |
sizeLong(CachePeekMode... peekModes)
Gets the number of all entries cached across all nodes as a long value.
|
IgniteCache<K,V> |
withAsync()
Gets instance of this component with asynchronous mode enabled.
|
IgniteCache<K,V> |
withExpiryPolicy(javax.cache.expiry.ExpiryPolicy plc)
Returns cache with the specified expired policy set.
|
<K1,V1> IgniteCache<K1,V1> |
withKeepBinary()
Returns cache that will operate with binary objects.
|
IgniteCache<K,V> |
withNoRetries() |
IgniteCache<K,V> |
withSkipStore() |
deregisterCacheEntryListener, getCacheManager, getName, isClosed, iterator, loadAll, registerCacheEntryListener, unwrapfuture, isAsyncIgniteCache<K,V> withAsync()
withAsync in interface IgniteAsyncSupport<C extends javax.cache.configuration.Configuration<K,V>> C getConfiguration(Class<C> clazz)
@Deprecated 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)
This method does not modify existing cache instance.
plc - Expire policy to use.IgniteCache<K,V> withSkipStore()
IgniteCache<K,V> withNoRetries()
<K1,V1> IgniteCache<K1,V1> withKeepBinary()
Cache returned by this method will not be forced to deserialize binary objects, so keys and values will be returned from cache API methods without changes. Therefore, signature of the cache can contain only following types:
org.apache.ignite.binary.BinaryObject for binary classesString and array of StringsUUID and array of UUIDsDate and array of DatesTimestamp and array of Timestamps
For example, if you use Integer as a key and Value class as a value
(which will be stored in binary format), you should acquire following projection
to avoid deserialization:
IgniteCacheprj = cache.withKeepBinary(); // Value is not deserialized and returned in binary format. BinaryObject po = prj.get(1);
Note that this method makes sense only if cache is working in binary mode if default marshaller is used. If not, this method is no-op and will return current cache.
@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
peekModes value isn't defined,
only size of primary copies across all nodes will be returned. This behavior is identical to calling
this method with CachePeekMode.PRIMARY peek mode.
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@IgniteAsyncSupported long sizeLong(CachePeekMode... peekModes) throws javax.cache.CacheException
peekModes value
isn't defined, only size of primary copies across all nodes will be returned. This behavior is identical to
calling this method with CachePeekMode.PRIMARY peek mode.
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.CacheExceptionint localSize(CachePeekMode... peekModes)
peekModes value isn't defined,
only size of primary copies will be returned. This behavior is identical to calling this method with
CachePeekMode.PRIMARY peek mode.peekModes - Optional peek modes. If not provided, then total cache size is returned.long localSizeLong(CachePeekMode... peekModes)
peekModes value isn't
defined, only size of primary copies will be returned. This behavior is identical to calling this method with
CachePeekMode.PRIMARY peek mode.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.EntryProcessorResults of the processing per key,
if any, defined by the EntryProcessor implementation. No mappings
will be returned for EntryProcessors that return a
null value for a key.@IgniteAsyncSupported V get(K key)
@IgniteAsyncSupported CacheEntry<K,V> getEntry(K key)
If the cache is configured to use read-through, and get would return null
because the entry is missing from the cache, the Cache's CacheLoader
is called in an attempt to load the entry.
key - the key whose associated value is to be returnedIllegalStateException - if the cache is Cache.isClosed()NullPointerException - if the key is nulljavax.cache.CacheException - if there is a problem fetching the valueClassCastException - 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@IgniteAsyncSupported Collection<CacheEntry<K,V>> getEntries(Set<? extends K> keys)
Cache.
If the cache is configured read-through, and a get for a key would
return null because an entry is missing from the cache, the Cache's
CacheLoader is called in an attempt to load the entry. If an
entry cannot be loaded for a given key, the key will not be present in
the returned Collection.
keys - The keys whose associated values are to be returned.NullPointerException - if keys is null or if keys contains a nullIllegalStateException - if the cache is Cache.isClosed()javax.cache.CacheException - if there is a problem fetching the valuesClassCastException - 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@IgniteAsyncSupported Map<K,V> getAllOutTx(Set<? extends K> keys)
keys - The keys whose associated values are to be returned.@IgniteAsyncSupported boolean containsKey(K key)
@IgniteAsyncSupported boolean containsKeys(Set<? extends K> keys)
Cache contains entries for the specified keys.keys - Key whose presence in this cache is to be tested.True if this cache contains a mapping for the specified 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()
The order that the individual entries are removed is undefined.
For every mapping that exists the following are called:
CacheEntryRemovedListenersCacheWriterCacheWriter is not called.
This operation is not transactional. It calls broadcast closure that deletes all primary keys from remote nodes.
This is potentially an expensive operation as listeners are invoked.
Use clear() to avoid this.
removeAll in interface javax.cache.Cache<K,V>IllegalStateException - if the cache is Cache.isClosed()javax.cache.CacheException - if there is a problem during the removeclear(),
CacheWriter.deleteAll(java.util.Collection<?>)@IgniteAsyncSupported void clear()
@IgniteAsyncSupported void clear(K key)
CacheWriters. 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<? extends K> keys)
CacheWriters. 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)
CacheWriters. 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<? extends K> keys)
CacheWriters. 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.
An instance of entry processor must be stateless as it may be invoked multiple times on primary and backup nodes in the cache. It is guaranteed that the value passed to the entry processor will be always the same.
key - the key to the entryentryProcessor - the CacheEntryProcessor to invokearguments - additional arguments to pass to the
CacheEntryProcessorCacheEntryProcessor 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 Cachejavax.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.Entrys
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 EntryProcessorResults, 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.
An instance of entry processor must be stateless as it may be invoked multiple times on primary and backup nodes in the cache. It is guaranteed that the value passed to the entry processor will be always the same.
keys - the set of keys for entries to processentryProcessor - the CacheEntryProcessor to invokeargs - additional arguments to pass to the
CacheEntryProcessorEntryProcessorResults of the processing per key,
if any, defined by the CacheEntryProcessor implementation. No mappings
will be returned for CacheEntryProcessors 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 CacheCacheEntryProcessorvoid close()
For local cache equivalent to destroy().
For distributed caches, if called on clients, stops client cache, if called on a server node,
just closes this cache instance and does not destroy cache data.
After cache instance is closed another IgniteCache instance for the same
cache can be created using Ignite.cache(String) method.
void destroy()
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
IgniteConfiguration.setConsistentId(Serializable) 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()
CacheMetrics metrics(ClusterGroup grp)
grp - Cluster group.CacheMetricsMXBean mxBean()
Follow @ApacheIgnite
Ignite Fabric : ver. 1.5.11 Release Date : April 8 2016