K
- the type of key.V
- the type of value.public interface ICache<K,V> extends javax.cache.Cache<K,V>, PrefixedDistributedObject
ICache
interface is the Cache
extension offered by
Hazelcast JCache.There are three different types of extensions methods provided:
ExpiryPolicy
parameter
to apply a special expiration to that specific operation, andsize()
) 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 the
ICache
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 term Async; for example, the asynchronous version of Cache.get(Object)
is getAsync(Object)
.
These methods return an ICompletableFuture
that can be used to get the result by
either implementing a callback based on ExecutionCallback
, or waiting for the operation to be
completed in a blocking fashion Future.get()
or
Future.get(long, java.util.concurrent.TimeUnit)
.
In a reactive way:
ICompletableFuture<Value> future = unwrappedCache.getAsync( "key-1" ) ; future.andThen( new ExecutionCallback() { public void onResponse( Value value ) { System.out.println( value ); } public void onFailure( Throwable throwable ) { throwable.printStackTrace(); } } );Or in a blocking way:
ICompletableFuture<Value> future = unwrappedCache.getAsync( "key-1" ) ; Value value = future.get(); System.out.println( value );
Custom ExpirePolicy:
For most of the typical operations, Hazelcast provides overloaded versions with an additional
ExpiryPolicy
parameter to configure a different expiration policy from the
default one set in the CompleteConfiguration
passed to the cache
creation. Therefore the Cache.put(Object, Object)
operation has an overload
put(Object, Object, javax.cache.expiry.ExpiryPolicy)
to pass in the
special policy.
Important: The overloads use an instance of ExpiryPolicy
, not
a Factory
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 new ICache
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.
Cache
Modifier and Type | Method and Description |
---|---|
String |
addPartitionLostListener(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 custom
ExpiryPolicy . |
Map<K,V> |
getAll(Set<? extends K> keys,
javax.cache.expiry.ExpiryPolicy expiryPolicy)
Gets a collection of entries from the cache with custom expiry policy, returning them as
Map 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 custom
ExpiryPolicy ,
returning an existing value if one existed. |
ICompletableFuture<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.
|
ICompletableFuture<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 custom
ExpiryPolicy . |
ICompletableFuture<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
custom
ExpiryPolicy and returns the previously assigned value. |
ICompletableFuture<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.
|
ICompletableFuture<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
custom
ExpiryPolicy and returns the previously assigned value. |
ICompletableFuture<V> |
getAsync(K key)
Asynchronously retrieves the mapped value of the given key using a custom
ExpiryPolicy . |
ICompletableFuture<V> |
getAsync(K key,
javax.cache.expiry.ExpiryPolicy expiryPolicy)
Asynchronously gets an entry from cache using a custom
ExpiryPolicy . |
CacheStatistics |
getLocalCacheStatistics()
Directly access local Cache Statistics.
|
boolean |
isDestroyed()
Determines whether this Cache instance has been destroyed.
|
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 custom
ExpiryPolicy . |
void |
putAll(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 custom
ExpiryPolicy . |
ICompletableFuture<Void> |
putAsync(K key,
V value)
Asynchronously associates the specified value with the specified key in the cache.
|
ICompletableFuture<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 custom
ExpiryPolicy . |
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.
|
ICompletableFuture<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.
|
ICompletableFuture<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.
|
ICompletableFuture<Boolean> |
removeAsync(K key)
Asynchronously removes the mapping for a key from this cache if it is present.
|
ICompletableFuture<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 of oldValue.
|
boolean |
removePartitionLostListener(String 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 custom
ExpiryPolicy . |
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 specified
newValue if and only if the currently assigned value equals the value of
oldValue using a custom
ExpiryPolicy . |
ICompletableFuture<Boolean> |
replaceAsync(K key,
V value)
Asynchronously replaces the assigned value of the given key by the specified value.
|
ICompletableFuture<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 custom
ExpiryPolicy . |
ICompletableFuture<Boolean> |
replaceAsync(K key,
V oldValue,
V newValue)
Asynchronously replaces the currently assigned value for the given key with the specified
newValue if and only if the currently assigned value equals the value of
oldValue.
|
ICompletableFuture<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 specified
newValue if and only if the currently assigned value equals the value of
oldValue using a custom
ExpiryPolicy . |
boolean |
setExpiryPolicy(K key,
javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the given
ExpiryPolicy . |
void |
setExpiryPolicy(Set<? extends K> keys,
javax.cache.expiry.ExpiryPolicy expiryPolicy)
Associates the specified key with the given
ExpiryPolicy . |
int |
size()
Total entry count.
|
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
forEach, spliterator
getPrefixedName
getName, getPartitionKey, getServiceName
boolean setExpiryPolicy(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
expiryPolicy
takes precedence for this particular key
against any cache wide expiry policy.
If key
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.key
- The key that is associated with the specified expiry policy.expiryPolicy
- custom expiry policy for this operationtrue
if the entry exists and its expiry policy is changed, false
otherwiseNullPointerException
- if keys
or expiryPolicy
is null.void setExpiryPolicy(Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
expiryPolicy
takes precedence for these particular keys
against any cache wide expiry policy.
If some keys in keys
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.keys
- The keys that are associated with the specified expiry policy.expiryPolicy
- custom expiry policy for this operationNullPointerException
- if keys
or expiryPolicy
is null.ICompletableFuture<V> getAsync(K key)
ExpiryPolicy
. If no mapping exists null is returned.
If the cache is configured for read-through operation mode, the underlying
configured CacheLoader
might be called to retrieve
the value of the key from any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
key
- The key whose associated value is to be returned.NullPointerException
- if given key is nulljavax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- if the cache is Cache.isClosed()
javax.cache.Cache#get(K)
,
ICompletableFuture
ICompletableFuture<V> getAsync(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
If the cache is configured for read-through operation mode, the underlying
configured CacheLoader
might be called to retrieve
the value of the key from any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
key
- The key whose associated value is to be returned.expiryPolicy
- The custom expiry policy for this operation,
a null value is equivalent to getAsync(Object)
.NullPointerException
- if given key is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- if the cache is Cache.isClosed()
.javax.cache.Cache#get(K)
,
ICompletableFuture
ICompletableFuture<Void> putAsync(K key, V value)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
key
- The key whose associated value is to be returned.value
- The value to be associated with the specified key.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#put(K, V)
,
ICompletableFuture
ICompletableFuture<Void> putAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to putAsync(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#put(K, V)
,
ICompletableFuture
ICompletableFuture<Boolean> putIfAbsentAsync(K key, V value)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
key
- The key that is associated with the specified value.value
- The value to which the specified key is associated.NullPointerException
- if the given key or value is nulljavax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#putIfAbsent(K, V)
,
ICompletableFuture
ICompletableFuture<Boolean> putIfAbsentAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to
putIfAbsentAsync(Object, Object)
NullPointerException
- if the given key or value is nulljavax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#putIfAbsent(K, V)
,
ICompletableFuture
ICompletableFuture<V> getAndPutAsync(K key, V value)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
key
- The key whose associated value is to be returned.value
- The value that is associated with the specified key.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndPut(K, V)
,
ICompletableFuture
ICompletableFuture<V> getAndPutAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to getAndPutAsync(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndPut(K, V)
,
ICompletableFuture
ICompletableFuture<Boolean> removeAsync(K key)
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
key
- The key whose mapping is to be removed.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- if the cache is Cache.isClosed()
.javax.cache.Cache#remove(K)
,
ICompletableFuture
ICompletableFuture<Boolean> removeAsync(K key, V oldValue)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
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.NullPointerException
- if the given key or oldValue is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- if the cache is Cache.isClosed()
.javax.cache.Cache#remove(K, V)
,
ICompletableFuture
ICompletableFuture<V> getAndRemoveAsync(K key)
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
key
- The key to be removed and whose associated value is to be returned.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- if the cache is Cache.isClosed()
.javax.cache.Cache#getAndRemove(K)
,
ICompletableFuture
ICompletableFuture<Boolean> replaceAsync(K key, V value)
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
key
- The key whose associated value is to be replaced.value
- The new value to be associated with the specified key.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#replace(K, V)
,
ICompletableFuture
ICompletableFuture<Boolean> replaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to replaceAsync(Object, Object)
NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#replace(K, V)
,
ICompletableFuture
ICompletableFuture<Boolean> replaceAsync(K key, V oldValue, V newValue)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
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.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.IllegalStateException
- 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.Cache#replace(K, V, V)
,
ICompletableFuture
ICompletableFuture<Boolean> replaceAsync(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
The resulting ICompletableFuture
instance may throw a
ClassCastException
as the operations result if the Cache
is configured to perform runtime-type-checking, and the key or value types are incompatible
with those that have been configured for the Cache
.
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 to replaceAsync(Object, Object, Object)
.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.IllegalStateException
- 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.Cache#replace(K, V, V)
,
ICompletableFuture
ICompletableFuture<V> getAndReplaceAsync(K key, V value)
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
key
- The key whose value is replaced.value
- The new value to be associated with the specified key.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndReplace(K, V)
,
ICompletableFuture
ICompletableFuture<V> getAndReplaceAsync(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
and returns the previously assigned value.
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to Cache.getAndReplace(Object, Object)
NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndReplace(K, V)
,
ICompletableFuture
V get(K key, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
If no mapping exists null is returned.
If the cache is configured for read-through operation mode, the underlying
configured CacheLoader
might be called to retrieve
the value of the key from any kind of external resource.
key
- The key whose mapped value is to be returned.expiryPolicy
- The custom expiry policy for this operation,
a null value is equivalent to Cache.get(Object)
.NullPointerException
- if the given key is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#get(K)
Map<K,V> getAll(Set<? extends K> keys, javax.cache.expiry.ExpiryPolicy expiryPolicy)
Map
of the values associated with the set of keys requested.
If the cache is configured for read-through operation mode, the underlying
configured CacheLoader
might be called to retrieve
the values of the keys from any kind of external resource.
keys
- The keys whose associated values are to be returned.expiryPolicy
- The custom expiry policy for this operation,
a null value is equivalent to Cache.getAll(java.util.Set)
.NullPointerException
- if the given keys are null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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
.Cache.getAll(java.util.Set)
void put(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.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 to Cache.put(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#put(K, V)
V getAndPut(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
,
returning an existing value if one existed.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 to Cache.getAndPut(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndPut(K, V)
void putAll(Map<? extends K,? extends V> map, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the values of the keys to any kind of external resource.
map
- The mappings to be stored in this cache.expiryPolicy
- The custom expiry policy for this operation,
a null value is equivalent to Cache.putAll(java.util.Map)
.NullPointerException
- if the given map is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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
.Cache.putAll(java.util.Map)
boolean putIfAbsent(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to Cache.putIfAbsent(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#putIfAbsent(K, V)
boolean replace(K key, V oldValue, V newValue, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
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
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to Cache.replace(Object, Object, Object)
.NullPointerException
- if given key, oldValue or newValue is nulljavax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#replace(K, V, V)
boolean replace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
.
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to Cache.replace(Object, Object)
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.IllegalStateException
- 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.Cache#replace(K, V)
V getAndReplace(K key, V value, javax.cache.expiry.ExpiryPolicy expiryPolicy)
ExpiryPolicy
and returns the previously assigned value.
If the cache is configured for write-through operation mode, the underlying
configured CacheWriter
might be called to store
the value of the key to any kind of external resource.
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 to Cache.getAndReplace(Object, Object)
.NullPointerException
- if the given key or value is null.javax.cache.CacheException
- if any exception
happens while invoking the request, other exceptions are wrapped.IllegalStateException
- 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.Cache#getAndReplace(K, V)
int size()
Integer.MAX_VALUE
elements, returns Integer.MAX_VALUE
.void destroy()
destroy
in interface DistributedObject
CacheManager.destroyCache(String)
boolean isDestroyed()
true
if this Cache instance is destroyed; false
if it is still open.CacheStatistics getLocalCacheStatistics()
String addPartitionLostListener(CachePartitionLostListener listener)
removePartitionLostListener(String)
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.listener
- the added CachePartitionLostListener.NullPointerException
- if listener is null.removePartitionLostListener(String)
boolean removePartitionLostListener(String id)
id
- ID of registered listener.NullPointerException
- if the given ID is null.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:
Iterator.next()
may return null if the entry is no
longer present, has expired or has been evicted.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.IllegalStateException
- if the cache is Cache.isClosed()
Cache.iterator()
Copyright © 2020 Hazelcast, Inc.. All Rights Reserved.