Interface ICache<K,V>
-
- Type Parameters:
K
- the type of key.V
- the type of value.
- All Superinterfaces:
java.lang.AutoCloseable
,javax.cache.Cache<K,V>
,java.io.Closeable
,DistributedObject
,java.lang.Iterable<javax.cache.Cache.Entry<K,V>>
,PrefixedDistributedObject
public interface ICache<K,V> extends javax.cache.Cache<K,V>, PrefixedDistributedObject
ThisICache
interface is theCache
extension offered by Hazelcast JCache.
In addition to the standard set of JCache methods defined in the JSR 107 specification, Hazelcast provides additional operations to support a broader range of programing styles.There are three different types of extensions methods provided:
- asynchronous version of typical blocking cache operations (due to remote calls),
- typical cache operations, providing a custom
ExpiryPolicy
parameter to apply a special expiration to that specific operation, and - common collection-like operations (e.g.
size()
) or typical Hazelcast-list additions (e.g.destroy()
).
To take advantage of the methods of this interface, the
Cache
instance needs to be unwrapped as defined in the JSR 107 standard (Cache.unwrap(Class)
) by providing theICache
interface parameter.ICache<Key , Value> unwrappedCache = cache.unwrap( ICache.class );
The unwrapped cache instance can now be used for both ICache and Cache operations.Asynchronous operations:
For most of the typical operations, Hazelcast provides asynchronous versions to program in a more reactive styled way. All asynchronous operations follow the same naming pattern: the operation's name from JCache extended by the termAsync
; for example, the asynchronous version ofCache.get(Object)
isgetAsync(Object)
.
These methods return aCompletionStage
that can be used to chain further computation stages. Alternatively, aCompletableFuture
can be obtained viaCompletionStage.toCompletableFuture()
to wait for the operation to be completed in a blocking fashion withFuture.get()
orFuture.get(long, java.util.concurrent.TimeUnit)
.In a reactive way:
CompletionStage<Value> stage = unwrappedCache.getAsync( "key-1" ) ; stage.thenAcceptAsync(value -> { System.out.println(value); });
Or in a blocking way:CompletionStage<Value> stage = unwrappedCache.getAsync( "key-1" ) ; Value value = stage.toCompletableFuture().get(); System.out.println( value );
Execution properties of returnedCompletionStage
sActions supplied for dependent completions of non-async methods and async methods without an explicit
Executor
argument are performed by theForkJoinPool.commonPool()
(unless it does not support a parallelism level of at least 2, in which case a newThread
is created per task).Dependent actions can be registered on the returned
CompletionStage
. Their execution followsCompletableFuture
execution conventions:- dependent actions registered by non-async methods may be executed by the thread that completes the current CompletableFuture or by any other caller of a completion method.
- dependent actions registered by default async methods without an explicit
Executor
argument are executed byForkJoinPool.commonPool()
unless its parallelism level is less than 2, in which case a newThread
is created to run each action
For most of the typical operations, Hazelcast provides overloaded versions with an additionalExpiryPolicy
parameter to configure a different expiration policy from the default one set in theCompleteConfiguration
passed to the cache creation. Therefore theCache.put(Object, Object)
operation has an overloadput(Object, Object, javax.cache.expiry.ExpiryPolicy)
to pass in the special policy.Important: The overloads use an instance of
ExpiryPolicy
, not aFactory
instance as is used in the configuration.unwrappedCache.put( "key", "value", new AccessedExpiryPolicy( Duration.ONE_DAY ) );
Split-brain
Behaviour of
ICache
under split-brain scenarios should be taken into account when using this data structure. During a split, each partitioned cluster will either create a brand newICache
or it will continue to use the primary or back-up version.As a defensive mechanism against such inconsistency, consider using the in-built split-brain protection for
ICache
. Using this functionality it is possible to restrict operations in smaller partitioned clusters. It should be noted that there is still an inconsistency window between the time of the split and the actual detection. Therefore using this reduces the window of inconsistency but can never completely eliminate it.- Since:
- 3.3.1
- See Also:
Cache
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.util.UUID
addPartitionLostListener(com.hazelcast.cache.impl.event.CachePartitionLostListener listener)
Adds a CachePartitionLostListener.void
destroy()
Closes the cache.V
get(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Retrieves the mapped value of the given key using a customExpiryPolicy
.java.util.Map<K,V>
getAll(java.util.Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Gets a collection of entries from the cache with custom expiry policy, returning them asMap
of the values associated with the set of keys requested.V
getAndPut(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified value with the specified key in this cache using a customExpiryPolicy
, returning an existing value if one existed.java.util.concurrent.CompletionStage<V>
getAndPutAsync(K key, V value)
Asynchronously associates the specified value with the specified key in this cache, returning an existing value if one existed.java.util.concurrent.CompletionStage<V>
getAndPutAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified value with the specified key in this cache, returning an existing value if one existed using a customExpiryPolicy
.java.util.concurrent.CompletionStage<V>
getAndRemoveAsync(K key)
Asynchronously removes the entry for a key and returns the previously assigned value or null if no value was assigned.V
getAndReplace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the assigned value of the given key by the specified value using a customExpiryPolicy
and returns the previously assigned value.java.util.concurrent.CompletionStage<V>
getAndReplaceAsync(K key, V value)
Asynchronously replaces the assigned value of the given key by the specified value and returns the previously assigned value.java.util.concurrent.CompletionStage<V>
getAndReplaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the assigned value of the given key by the specified value using a customExpiryPolicy
and returns the previously assigned value.java.util.concurrent.CompletionStage<V>
getAsync(K key)
Asynchronously retrieves the mapped value of the given key using a customExpiryPolicy
.java.util.concurrent.CompletionStage<V>
getAsync(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously gets an entry from cache using a customExpiryPolicy
.CacheStatistics
getLocalCacheStatistics()
Directly access local Cache Statistics.boolean
isDestroyed()
Determines whether this Cache instance has been destroyed.java.util.Iterator<javax.cache.Cache.Entry<K,V>>
iterator(int fetchSize)
Creates and returns a cluster wide iterator to iterate on all entries owned by this cache.void
put(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified value with the specified key in the cache using a customExpiryPolicy
.void
putAll(java.util.Map<? extends K,? extends V> map, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Copies all of the entries from the given map to the cache using a customExpiryPolicy
.java.util.concurrent.CompletionStage<java.lang.Void>
putAsync(K key, V value)
Asynchronously associates the specified value with the specified key in the cache.java.util.concurrent.CompletionStage<java.lang.Void>
putAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified value with the specified key in the cache using a customExpiryPolicy
.boolean
putIfAbsent(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key.java.util.concurrent.CompletionStage<java.lang.Boolean>
putIfAbsentAsync(K key, V value)
Asynchronously associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key.java.util.concurrent.CompletionStage<java.lang.Boolean>
putIfAbsentAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key.java.util.concurrent.CompletionStage<java.lang.Boolean>
removeAsync(K key)
Asynchronously removes the mapping for a key from this cache if it is present.java.util.concurrent.CompletionStage<java.lang.Boolean>
removeAsync(K key, V oldValue)
Asynchronously removes the mapping for the given key if and only if the currently mapped value equals to the value ofoldValue
.boolean
removePartitionLostListener(java.util.UUID id)
Removes the specified cache partition lost listener.boolean
replace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the assigned value of the given key by the specified value using a customExpiryPolicy
.boolean
replace(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
using a customExpiryPolicy
.java.util.concurrent.CompletionStage<java.lang.Boolean>
replaceAsync(K key, V value)
Asynchronously replaces the assigned value of the given key by the specified value.java.util.concurrent.CompletionStage<java.lang.Boolean>
replaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the assigned value of the given key by the specified value using a customExpiryPolicy
.java.util.concurrent.CompletionStage<java.lang.Boolean>
replaceAsync(K key, V oldValue, V newValue)
Asynchronously replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
.java.util.concurrent.CompletionStage<java.lang.Boolean>
replaceAsync(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
using a customExpiryPolicy
.void
setExpiryPolicy(java.util.Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the givenExpiryPolicy
.boolean
setExpiryPolicy(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the givenExpiryPolicy
.int
size()
Total entry count.-
Methods inherited from interface javax.cache.Cache
clear, close, containsKey, deregisterCacheEntryListener, get, getAll, getAndPut, getAndRemove, getAndReplace, getCacheManager, getConfiguration, getName, invoke, invokeAll, isClosed, iterator, loadAll, put, putAll, putIfAbsent, registerCacheEntryListener, remove, remove, removeAll, removeAll, replace, replace, unwrap
-
Methods inherited from interface com.hazelcast.core.DistributedObject
getDestroyContextForTenant, getName, getPartitionKey, getServiceName
-
Methods inherited from interface com.hazelcast.core.PrefixedDistributedObject
getPrefixedName
-
-
-
-
Method Detail
-
setExpiryPolicy
boolean setExpiryPolicy(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the givenExpiryPolicy
.expiryPolicy
takes precedence for this particularkey
against any cache wide expiry policy. Ifkey
does not exist or is already expired, this call makes no changes to entries stored in this cache. Note: New time-to-live duration is calculated using newly added entry policy's getExpiryForUpdate method immediately after this operation succeeds.- Parameters:
key
- The key that is associated with the specified expiry policy.expiryPolicy
- custom expiry policy for this operation- Returns:
true
if the entry exists and its expiry policy is changed,false
otherwise- Throws:
java.lang.NullPointerException
- ifkeys
orexpiryPolicy
is null.- Since:
- 3.11
-
setExpiryPolicy
void setExpiryPolicy(java.util.Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the givenExpiryPolicy
.expiryPolicy
takes precedence for these particularkeys
against any cache wide expiry policy. If some keys inkeys
do not exist or are already expired, this call has no effect for those. Note: New time-to-live duration is calculated using newly added entry policy's getExpiryForUpdate method immediately after this operation succeeds.- Parameters:
keys
- The keys that are associated with the specified expiry policy.expiryPolicy
- custom expiry policy for this operation- Throws:
java.lang.NullPointerException
- ifkeys
orexpiryPolicy
is null.- Since:
- 3.11
-
getAsync
java.util.concurrent.CompletionStage<V> getAsync(K key)
Asynchronously retrieves the mapped value of the given key using a customExpiryPolicy
. If no mapping existsnull
is returned.If the cache is configured for
read-through
operation mode, the underlying configuredCacheLoader
might be called to retrieve the value of the key from any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key whose associated value is to be returned.- Returns:
- CompletionStage retrieve the value assigned to the given key.
- Throws:
java.lang.NullPointerException
- if given key is nulljavax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
- See Also:
Cache.get(Object)
-
getAsync
java.util.concurrent.CompletionStage<V> getAsync(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously gets an entry from cache using a customExpiryPolicy
.If the cache is configured for
read-through
operation mode, the underlying configuredCacheLoader
might be called to retrieve the value of the key from any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key whose associated value is to be returned.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent togetAsync(Object)
.- Returns:
- CompletionStage retrieve the value assigned to the given key.
- Throws:
java.lang.NullPointerException
- if given key is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.- See Also:
Cache.get(Object)
-
putAsync
java.util.concurrent.CompletionStage<java.lang.Void> putAsync(K key, V value)
Asynchronously associates the specified value with the specified key in the cache.In case a previous assignment already exists, the previous value is overridden by the new given value.
If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose associated value is to be returned.value
- The value to be associated with the specified key.- Returns:
- CompletionStage notify when the operation succeeds.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.put(Object, Object)
-
putAsync
java.util.concurrent.CompletionStage<java.lang.Void> putAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified value with the specified key in the cache using a customExpiryPolicy
.In case a previous assignment already exists, the previous value is overridden by the new given value.
If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose associated value is to be returned.value
- The value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toputAsync(Object, Object)
.- Returns:
- CompletionStage notify when the operation succeeds.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.put(Object, Object)
-
putIfAbsentAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> putIfAbsentAsync(K key, V value)
Asynchronously associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key.This is equivalent to:
if (!cache.containsKey(key)) {} cache.put(key, value); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key that is associated with the specified value.value
- The value to which the specified key is associated.- Returns:
- CompletionStage notify if a previous value was assigned with the key
- Throws:
java.lang.NullPointerException
- if the given key or value is nulljavax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
java.lang.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 theCache
- See Also:
Cache.putIfAbsent(Object, Object)
-
putIfAbsentAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> putIfAbsentAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key. using a customExpiryPolicy
.This is equivalent to:
if (!cache.containsKey(key)) {} cache.put(key, value); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key that is associated with the specified value.value
- The value to which the specified key is associated.expiryPolicy
- custom expiry policy for this operation, a null value is equivalent toputIfAbsentAsync(Object, Object)
- Returns:
- CompletionStage notify if a previous value was assigned with the key
- Throws:
java.lang.NullPointerException
- if the given key or value is nulljavax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
java.lang.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 theCache
- See Also:
Cache.putIfAbsent(Object, Object)
-
getAndPutAsync
java.util.concurrent.CompletionStage<V> getAndPutAsync(K key, V value)
Asynchronously associates the specified value with the specified key in this cache, returning an existing value if one existed.In case a previous assignment already exists, the previous value is overridden by the new given value and the previous value is returned to the caller. This is equivalent to the
Map.put(Object, Object)
operation.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose associated value is to be returned.value
- The value that is associated with the specified key.- Returns:
- CompletionStage retrieve a possible previously assigned value for the given key.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndPut(Object, Object)
-
getAndPutAsync
java.util.concurrent.CompletionStage<V> getAndPutAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously associates the specified value with the specified key in this cache, returning an existing value if one existed using a customExpiryPolicy
.In case a previous assignment already exists, the previous value is overridden by the new given value and the previous value is returned to the caller. This is equivalent to the
Map.put(Object, Object)
operation.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose associated value is to be returned.value
- The value to associate with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent togetAndPutAsync(Object, Object)
.- Returns:
- CompletionStage retrieve a possible previously assigned value for the given key.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndPut(Object, Object)
-
removeAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> removeAsync(K key)
Asynchronously removes the mapping for a key from this cache if it is present.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key whose mapping is to be removed.- Returns:
- CompletionStage notify if mapping could be removed or not.
- Throws:
java.lang.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.- See Also:
Cache.remove(Object)
-
removeAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> removeAsync(K key, V oldValue)
Asynchronously removes the mapping for the given key if and only if the currently mapped value equals to the value ofoldValue
.This is equivalent to:
if (cache.containsKey(key) && equals(cache.get(key), oldValue) { cache.remove(key); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key whose mapping is to be removed if the mapped value is oldValue.oldValue
- The value expected to be associated with the specified key.- Returns:
- CompletionStage notify if mapping could be removed or not.
- Throws:
java.lang.NullPointerException
- if the given key or oldValue is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.- See Also:
Cache.remove(Object, Object)
-
getAndRemoveAsync
java.util.concurrent.CompletionStage<V> getAndRemoveAsync(K key)
Asynchronously removes the entry for a key and returns the previously assigned value or null if no value was assigned.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key to be removed and whose associated value is to be returned.- Returns:
- CompletionStage retrieve a possible previously assigned value for the removed key.
- Throws:
java.lang.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.- See Also:
Cache.getAndRemove(Object)
-
replaceAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> replaceAsync(K key, V value)
Asynchronously replaces the assigned value of the given key by the specified value.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose associated value is to be replaced.value
- The new value to be associated with the specified key.- Returns:
- CompletionStage notify if the operation succeeds or not.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.replace(Object, Object)
-
replaceAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> replaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the assigned value of the given key by the specified value using a customExpiryPolicy
.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose assigned value is replaced by the specified value.value
- The specified value to be associated with the given key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toreplaceAsync(Object, Object)
- Returns:
- CompletionStage notify if the operation succeeds or not.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.replace(Object, Object)
-
replaceAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> replaceAsync(K key, V oldValue, V newValue)
Asynchronously replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
.This is equivalent to:
if (cache.containsKey(key) && equals(cache.get(key), oldValue) { cache.put(key, newValue); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key that will have its assigned value replaced.oldValue
- The old value expected to be associated with the specified key.newValue
- The new value to be associated with the specified key.- Returns:
- CompletionStage notify if the operation succeeds or not.
- Throws:
java.lang.NullPointerException
- if the given key, oldValue or newValue is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
java.lang.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 theCache
- See Also:
Cache.replace(Object, Object, Object)
-
replaceAsync
java.util.concurrent.CompletionStage<java.lang.Boolean> replaceAsync(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
using a customExpiryPolicy
.This is equivalent to:
if (cache.containsKey(key) && equals(cache.get(key), oldValue) { cache.put(key, newValue); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.The resulting
CompletionStage
instance may throw aClassCastException
as the operations result if theCache
is configured to perform runtime-type-checking, and the key or value types are incompatible with those that have been configured for theCache
.- Parameters:
key
- The key that will have its assigned value replaced.oldValue
- The old value expected to be associated with the specified key.newValue
- The new value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toreplaceAsync(Object, Object, Object)
.- Returns:
- CompletionStage to get notified if the operation succeed or not.
- Throws:
java.lang.NullPointerException
- if the given key, oldValue or newValue is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.replace(Object, Object, Object)
-
getAndReplaceAsync
java.util.concurrent.CompletionStage<V> getAndReplaceAsync(K key, V value)
Asynchronously replaces the assigned value of the given key by the specified value and returns the previously assigned value.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose value is replaced.value
- The new value to be associated with the specified key.- Returns:
- CompletionStage to retrieve a possible previously assigned value for the given key.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndReplace(Object, Object)
-
getAndReplaceAsync
java.util.concurrent.CompletionStage<V> getAndReplaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously replaces the assigned value of the given key by the specified value using a customExpiryPolicy
and returns the previously assigned value.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose value is replaced.value
- The new value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.getAndReplace(Object, Object)
- Returns:
- CompletionStage to retrieve a possible previously assigned value for the given key.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndReplace(Object, Object)
-
get
V get(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Retrieves the mapped value of the given key using a customExpiryPolicy
. If no mapping existsnull
is returned.If the cache is configured for
read-through
operation mode, the underlying configuredCacheLoader
might be called to retrieve the value of the key from any kind of external resource.- Parameters:
key
- The key whose mapped value is to be returned.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.get(Object)
.- Returns:
- The value assigned to the given key, or null if not assigned.
- Throws:
java.lang.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
- See Also:
Cache.get(Object)
-
getAll
java.util.Map<K,V> getAll(java.util.Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Gets a collection of entries from the cache with custom expiry policy, returning them asMap
of the values associated with the set of keys requested.If the cache is configured for
read-through
operation mode, the underlying configuredCacheLoader
might be called to retrieve the values of the keys from any kind of external resource.- Parameters:
keys
- The keys whose associated values are to be returned.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.getAll(java.util.Set)
.- Returns:
- A map of entries that were found for the given keys. Keys not found in the cache are not in the returned map.
- Throws:
java.lang.NullPointerException
- if the given keys are null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
java.lang.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 theCache
.- See Also:
Cache.getAll(java.util.Set)
-
put
void put(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified value with the specified key in the cache using a customExpiryPolicy
.- Parameters:
key
- The key that has the specified value associated with it.value
- The value to be associated with the key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.put(Object, Object)
.- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.put(Object, Object)
-
getAndPut
V getAndPut(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified value with the specified key in this cache using a customExpiryPolicy
, returning an existing value if one existed.- Parameters:
key
- The key that has the specified value associated with it.value
- The value to be associated with the key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.getAndPut(Object, Object)
.- Returns:
- The value previously assigned to the given key, or null if not assigned.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndPut(Object, Object)
-
putAll
void putAll(java.util.Map<? extends K,? extends V> map, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Copies all of the entries from the given map to the cache using a customExpiryPolicy
.Puts of single entries happen atomically but there is no transactional guarantee over the complete
putAll
operation. If other concurrent operations modify or remove all or single values of the provided map, the result is undefined.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the values of the keys to any kind of external resource.- Parameters:
map
- The mappings to be stored in this cache.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.putAll(java.util.Map)
.- Throws:
java.lang.NullPointerException
- if the given map is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.putAll(java.util.Map)
-
putIfAbsent
boolean putIfAbsent(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the given value if and only if there is not yet a mapping defined for the specified key.This is equivalent to:
if (!cache.containsKey(key)) {} cache.put(key, value); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key that is associated with the specified value.value
- The value that has the specified key associated with it.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.putIfAbsent(Object, Object)
.- Returns:
- true if a value was set, false otherwise.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.putIfAbsent(Object, Object)
-
replace
boolean replace(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the currently assigned value for the given key with the specifiednewValue
if and only if the currently assigned value equals the value ofoldValue
using a customExpiryPolicy
.This is equivalent to:
if (cache.containsKey(key) && equals(cache.get(key), oldValue) { cache.put(key, newValue); return true; } else { return false; }
except that the action is performed atomically.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key with the value to be replaced.oldValue
- The old value expected to be associated with the specified key.newValue
- The new value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.replace(Object, Object, Object)
.- Returns:
- true if a value was replaced, false otherwise.
- Throws:
java.lang.NullPointerException
- if given key, oldValue or newValue is nulljavax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.replace(Object, Object, Object)
-
replace
boolean replace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the assigned value of the given key by the specified value using a customExpiryPolicy
.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose value is replaced.value
- The new value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.replace(Object, Object)
- Returns:
- true if a value was replaced, false otherwise.
- Throws:
java.lang.NullPointerException
- if the given key, oldValue or newValue is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.replace(Object, Object)
-
getAndReplace
V getAndReplace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Atomically replaces the assigned value of the given key by the specified value using a customExpiryPolicy
and returns the previously assigned value.If the cache is configured for
write-through
operation mode, the underlying configuredCacheWriter
might be called to store the value of the key to any kind of external resource.- Parameters:
key
- The key whose value is replaced.value
- The new value to be associated with the specified key.expiryPolicy
- The custom expiry policy for this operation, a null value is equivalent toCache.getAndReplace(Object, Object)
.- Returns:
- The old value previously assigned to the given key.
- Throws:
java.lang.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception happens while invoking the request, other exceptions are wrapped.java.lang.IllegalStateException
- if the cache isCache.isClosed()
.java.lang.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 theCache
.- See Also:
Cache.getAndReplace(Object, Object)
-
size
int size()
Total entry count. If the cache contains more thanInteger.MAX_VALUE
elements, returnsInteger.MAX_VALUE
.- Returns:
- total entry count
-
destroy
void destroy()
Closes the cache. Clears the internal content and releases any resource.- Specified by:
destroy
in interfaceDistributedObject
- See Also:
CacheManager.destroyCache(String)
-
isDestroyed
boolean isDestroyed()
Determines whether this Cache instance has been destroyed.- Returns:
true
if this Cache instance is destroyed;false
if it is still open.
-
getLocalCacheStatistics
CacheStatistics getLocalCacheStatistics()
Directly access local Cache Statistics.- Returns:
- CacheStatistics instance or an empty statistics if not enabled.
-
addPartitionLostListener
java.util.UUID addPartitionLostListener(com.hazelcast.cache.impl.event.CachePartitionLostListener listener)
Adds a CachePartitionLostListener.The addPartitionLostListener returns a registration ID. This ID is needed to remove the CachePartitionLostListener using the
removePartitionLostListener(UUID)
method.There is no check for duplicate registrations, so if you register the listener twice, it will get events twice. IMPORTANT: Please @see com.hazelcast.partition.PartitionLostListener for weaknesses. IMPORTANT: Listeners registered from HazelcastClient may miss some of the cache partition lost events due to design limitations.
- Parameters:
listener
- the added CachePartitionLostListener.- Returns:
- returns the registration ID for the CachePartitionLostListener.
- Throws:
java.lang.NullPointerException
- if listener is null.- See Also:
removePartitionLostListener(UUID)
-
removePartitionLostListener
boolean removePartitionLostListener(java.util.UUID id)
Removes the specified cache partition lost listener. Returns silently if there is no such listener added before.- Parameters:
id
- ID of registered listener.- Returns:
- true if registration is removed, false otherwise.
- Throws:
java.lang.NullPointerException
- if the given ID is null.
-
iterator
java.util.Iterator<javax.cache.Cache.Entry<K,V>> iterator(int fetchSize)
Creates and returns a cluster wide iterator to iterate on all entries owned by this cache.
The ordering of iteration over entries is undefined.
During iteration, any entries that are:
- read will have their appropriate CacheEntryReadListeners notified.
- removed will have their appropriate CacheEntryRemoveListeners notified.
Iterator.next()
may return null if the entry is no longer present, has expired or has been evicted.- Parameters:
fetchSize
- size for fetching keys in bulk. This size can be thought of as page size for iteration. But notice that at every fetch, only keys are retrieved, not values. Values are retrieved on each iterate.- Throws:
java.lang.IllegalStateException
- if the cache isCache.isClosed()
- See Also:
Cache.iterator()
-
-