K
- key typeV
- value typepublic interface IMap<K,V> extends ConcurrentMap<K,V>, BaseMap<K,V>, Iterable<Map.Entry<K,V>>
This class is not a general-purpose ConcurrentMap
implementation! While this class implements the Map
interface,
it intentionally violates Map's
general contract, which mandates
the use of the equals
method when comparing objects. Instead of
the equals
method, this implementation compares the serialized
byte version of the objects.
Moreover, stored values are handled as having a value type semantics, while standard Java implementations treat them as having a reference type semantics.
Gotchas:
get
, containsKey
,
containsValue
, evict
, remove
, put
,
putIfAbsent
, replace
, lock
, unlock
, do
not use hashCode
and equals
implementations of keys.
Instead, they use hashCode
and equals
of binary (serialized)
forms of the objects.get
method returns a clone of original values, so modifying
the returned value does not change the actual value in the map. You should
put the modified value back to make changes visible to all nodes.
For additional info, see get(Object)
.keySet
, values
,
entrySet
, return an immutable collection clone of the values.
The collection is NOT backed by the map, so changes to the map are
NOT reflected in the collection.ConcurrentMap
and Map
. Under the hood they are typically
implemented as a sequence of more primitive map operations, therefore the
operations won't be executed atomically.
This class does not allow null
to be used as a key or
value.
Entry Processing
The following operations are lock-aware, since they operate on a single key only. If the key is locked, the EntryProcessor will wait until it acquires the lock.
However, there are following methods that run theEntryProcessor
on more than one entry.
These operations are not lock-aware.
The EntryProcessor
will process the entries no matter if they
are locked or not.
The user may however check if an entry is locked by casting the
Map.Entry
to LockAware
and invoking the
LockAware.isLocked()
method.
executeOnEntries(EntryProcessor)
executeOnEntries(EntryProcessor, Predicate)
executeOnKeys(Set, EntryProcessor)
EntryProcessor
and BackupEntryProcessor
.
Split-brain
Behaviour of IMap
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 IMap
or it
will continue to use the primary or back-up version.
When the split heals, Hazelcast by default, performs a
PutIfAbsentMergePolicy
.
Users can also decide to
specify their own map merge policies, these policies when used in
concert with
CRDTs (Convergent and Commutative
Replicated Data Types) can ensure against data loss during a split-brain.
As a defensive mechanism against such inconsistency, consider using the
in-built
split-brain protection for IMap
. 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.
Interactions with the map store
Maps can be configured to be backed by a map store to persist the entries.
In this case many of the IMap methods call MapLoader
or
MapStore
methods to load, store or remove data. Each method's
javadoc describes the way of its interaction with the map store.
Expiration and eviction
Expiration puts a limit on the maximum lifetime of an entry stored inside the map. When the entry expires it can't be retrieved from the map any longer and at some point in time it will be cleaned out from the map to free up the memory. There are two expiration policies:
time-to-live-seconds
setting, which has an infinite by default.
An individual entry may have its own TTL value assigned using one of the
methods accepting a TTL value, for instance using the
put
method. If there is no
TTL value provided for the individual entry, it inherits the value set
in the map configuration.
max-idle-seconds
setting, which has an infinite value
by default.
Both expiration policies may be used simultaneously on the map entries. In such case, the entry is considered expired if at least one of the policies marks it as expired.
Eviction puts a limit on the maximum size of the map. If the size of the
map grows larger than the maximum allowed size, an eviction policy decides
which item to evict from the map to reduce its size. The maximum allowed
size may be configured using the
max-size
setting
and the eviction policy may be configured using the
eviction-policy
setting as well.
By default, maps have no restrictions on the size and may grow arbitrarily
large.
Eviction may be enabled along with the expiration policies. In such case, the expiration policies continue to work as usual cleaning out the expired entries regardless of the map size.
Locked map entries are not the subjects for the expiration and eviction policies.
Mutating methods without TTL
Certain IMap
methods perform the entry set mutation and don't
accept TTL as a parameter. Entries created or updated by such methods are
subjects for the following TTL calculation procedure:
time-to-live-seconds
configuration setting. If this setting is not provided for the map, the
entry receives an infinite TTL value.
put
,
set
, putAsync
,
setAsync
,
tryPut
,
putAll
, setAll
,
putAllAsync
, setAllAsync
,
replace(Object, Object, Object)
and replace(Object, Object)
.
Asynchronous methods
Asynchronous methods return a CompletionStage
that can be used to
chain further computation stages. Alternatively, a CompletableFuture
can be obtained via CompletionStage.toCompletableFuture()
to wait
for the operation to complete in a blocking way.
Actions supplied for dependent completions of default non-async methods and async methods
without an explicit Executor
argument are performed
by the ForkJoinPool.commonPool()
(unless it does not
support a parallelism level of at least 2, in which case a new Thread
is
created per task).
ConcurrentMap
Modifier and Type | Method and Description |
---|---|
UUID |
addEntryListener(MapListener listener,
boolean includeValue)
Adds a
MapListener for this map. |
UUID |
addEntryListener(MapListener listener,
K key,
boolean includeValue)
Adds a
MapListener for this map. |
UUID |
addEntryListener(MapListener listener,
Predicate<K,V> predicate,
boolean includeValue)
Adds a
MapListener for this map. |
UUID |
addEntryListener(MapListener listener,
Predicate<K,V> predicate,
K key,
boolean includeValue)
Adds a
MapListener for this map. |
void |
addIndex(IndexConfig indexConfig)
Adds an index to this map for the specified entries so
that queries can run faster.
|
default void |
addIndex(IndexType type,
String... attributes)
Convenient method to add an index to this map with the given type and attributes.
|
String |
addInterceptor(MapInterceptor interceptor)
Adds an interceptor for this map.
|
UUID |
addLocalEntryListener(MapListener listener)
Adds a
MapListener for this map. |
UUID |
addLocalEntryListener(MapListener listener,
Predicate<K,V> predicate,
boolean includeValue)
Adds a
MapListener for this map. |
UUID |
addLocalEntryListener(MapListener listener,
Predicate<K,V> predicate,
K key,
boolean includeValue)
Adds a local entry listener for this map.
|
UUID |
addPartitionLostListener(MapPartitionLostListener listener)
Adds a MapPartitionLostListener.
|
<R> R |
aggregate(Aggregator<? super Map.Entry<K,V>,R> aggregator)
Applies the aggregation logic on all map entries and returns the result
|
<R> R |
aggregate(Aggregator<? super Map.Entry<K,V>,R> aggregator,
Predicate<K,V> predicate)
Applies the aggregation logic on map entries filtered with the Predicated and returns the result
|
void |
clear()
Clears the map and deletes the items from the backing map store.
|
V |
compute(K key,
BiFunction<? super K,? super V,? extends V> remappingFunction) |
V |
computeIfAbsent(K key,
Function<? super K,? extends V> mappingFunction) |
V |
computeIfPresent(K key,
BiFunction<? super K,? super V,? extends V> remappingFunction) |
boolean |
containsKey(Object key)
Returns
true if this map contains an entry for the specified
key. |
boolean |
containsValue(Object value) |
void |
delete(Object key)
Removes the mapping for the key from this map if it is present.
|
Set<Map.Entry<K,V>> |
entrySet()
Returns an immutable
Set clone of the mappings contained in this map. |
Set<Map.Entry<K,V>> |
entrySet(Predicate<K,V> predicate)
Queries the map based on the specified predicate and returns an immutable set of the matching entries.
|
boolean |
evict(K key)
Evicts the specified key from this map.
|
void |
evictAll()
Evicts all keys from this map except the locked ones.
|
<R> Map<K,R> |
executeOnEntries(EntryProcessor<K,V,R> entryProcessor)
Applies the user defined
EntryProcessor to the all entries in the map. |
<R> Map<K,R> |
executeOnEntries(EntryProcessor<K,V,R> entryProcessor,
Predicate<K,V> predicate)
Applies the user defined
EntryProcessor to the entries in the map which satisfy provided predicate. |
<R> R |
executeOnKey(K key,
EntryProcessor<K,V,R> entryProcessor)
Applies the user defined
EntryProcessor to the entry mapped by the key . |
<R> Map<K,R> |
executeOnKeys(Set<K> keys,
EntryProcessor<K,V,R> entryProcessor)
Applies the user defined
EntryProcessor to the entries mapped by the collection of keys. |
void |
flush()
If this map has a MapStore, this method flushes
all the local dirty entries.
|
void |
forceUnlock(K key)
Releases the lock for the specified key regardless of the lock owner.
|
default void |
forEach(BiConsumer<? super K,? super V> action) |
V |
get(Object key)
Returns the value for the specified key, or
null if this map does not contain this key. |
Map<K,V> |
getAll(Set<K> keys)
Returns an immutable map of entries for the given keys.
|
CompletionStage<V> |
getAsync(K key)
Asynchronously gets the given key.
|
EntryView<K,V> |
getEntryView(K key)
Returns the
EntryView for the specified key. |
LocalMapStats |
getLocalMapStats()
Returns LocalMapStats for this map.
|
QueryCache<K,V> |
getQueryCache(String name)
Returns corresponding
QueryCache instance for the supplied name or null. |
QueryCache<K,V> |
getQueryCache(String name,
MapListener listener,
Predicate<K,V> predicate,
boolean includeValue)
Creates an always up to date snapshot of this
IMap according to
the supplied parameters. |
QueryCache<K,V> |
getQueryCache(String name,
Predicate<K,V> predicate,
boolean includeValue)
Creates an always up to date snapshot of this
IMap according to the supplied parameters. |
boolean |
isLocked(K key)
Checks the lock for the specified key.
|
Iterator<Map.Entry<K,V>> |
iterator()
Returns an iterator over the entries of the map.
|
Iterator<Map.Entry<K,V>> |
iterator(int fetchSize)
Returns an iterator over the entries of the map.
|
Set<K> |
keySet()
Returns an immutable set clone of the keys contained in this map.
|
Set<K> |
keySet(Predicate<K,V> predicate)
Queries the map based on the specified predicate and
returns an immutable
Set clone of the keys of matching entries. |
void |
loadAll(boolean replaceExistingValues)
Loads all keys into the store.
|
void |
loadAll(Set<K> keys,
boolean replaceExistingValues)
Loads the given keys.
|
Set<K> |
localKeySet()
Returns the locally owned immutable set of keys.
|
Set<K> |
localKeySet(Predicate<K,V> predicate)
Returns an immutable set of the keys of matching locally owned entries.
|
void |
lock(K key)
Acquires the lock for the specified key.
|
void |
lock(K key,
long leaseTime,
TimeUnit timeUnit)
Acquires the lock for the specified key for the specified lease time.
|
V |
merge(K key,
V value,
BiFunction<? super V,? super V,? extends V> remappingFunction) |
<R> Collection<R> |
project(Projection<? super Map.Entry<K,V>,R> projection)
Applies the projection logic on all map entries and returns the result
|
<R> Collection<R> |
project(Projection<? super Map.Entry<K,V>,R> projection,
Predicate<K,V> predicate)
Applies the projection logic on map entries filtered with the Predicated and returns the result
|
V |
put(K key,
V value)
Associates the specified value with the specified key in this map.
|
V |
put(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Puts an entry into this map with a given TTL (time to live) value.
|
V |
put(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Puts an entry into this map with a given TTL (time to live) value and
max idle time value.
|
void |
putAll(Map<? extends K,? extends V> m) |
CompletionStage<Void> |
putAllAsync(Map<? extends K,? extends V> map)
Asynchronously copies all of the mappings from the specified map to this map.
|
CompletionStage<V> |
putAsync(K key,
V value)
Asynchronously puts the given key and value.
|
CompletionStage<V> |
putAsync(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Asynchronously puts the given key and value into this map with a given TTL (time to live) value.
|
CompletionStage<V> |
putAsync(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Asynchronously puts the given key and value into this map with a given
TTL (time to live) value and max idle time value.
|
V |
putIfAbsent(K key,
V value)
If the specified key is not already associated
with a value, associate it with the given value.
|
V |
putIfAbsent(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Puts an entry into this map with a given TTL (time to live) value,
if the specified key is not already associated with a value.
|
V |
putIfAbsent(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Puts an entry into this map with a given TTL (time to live) value and
max idle time value.
|
void |
putTransient(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Same as
put(Object, Object, long, TimeUnit)
except that the map store, if defined, will not be called to
load/store/persist the entry. |
void |
putTransient(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Same as
put(Object, Object, long, TimeUnit) except that the map
store, if defined, will not be called to load/store/persist the entry. |
V |
remove(Object key)
Removes the mapping for a key from this map if it is present.
|
boolean |
remove(Object key,
Object value)
Removes the entry for a key only if currently mapped to a given value.
|
void |
removeAll(Predicate<K,V> predicate)
Removes all entries which match with the supplied predicate.
|
CompletionStage<V> |
removeAsync(K key)
Asynchronously removes the given key, returning an
CompletionStage
on which the caller can register further computation stages to be invoked
upon remove operation completion or block waiting for the operation to
complete using one of blocking ways to wait on
CompletionStage.toCompletableFuture() . |
boolean |
removeEntryListener(UUID id)
Removes the specified entry listener.
|
boolean |
removeInterceptor(String id)
Removes the given interceptor for this map,
so it will not intercept operations anymore.
|
boolean |
removePartitionLostListener(UUID id)
Removes the specified map partition lost listener.
|
V |
replace(K key,
V value)
Replaces the entry for a key only if it is currently mapped to some value.
|
boolean |
replace(K key,
V oldValue,
V newValue)
Replaces the entry for a key only if currently mapped to a given value.
|
default void |
replaceAll(BiFunction<? super K,? super V,? extends V> function) |
void |
set(K key,
V value)
Puts an entry into this map without returning the old value
(which is more efficient than
put() ). |
void |
set(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Puts an entry into this map with a given TTL (time to live) value,
without returning the old value (which is more efficient than
put() ). |
void |
set(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Puts an entry into this map with a given TTL (time to live) value and
max idle time value without returning the old value (which is more
efficient than
put() ). |
void |
setAll(Map<? extends K,? extends V> map)
Copies all of the mappings from the specified map to this map without loading
non-existing elements from map store (which is more efficient than
putAll() ). |
CompletionStage<Void> |
setAllAsync(Map<? extends K,? extends V> map)
Asynchronously copies all of the mappings from the specified map to this map
without loading non-existing elements from map store.
|
CompletionStage<Void> |
setAsync(K key,
V value)
Asynchronously puts the given key and value.
|
CompletionStage<Void> |
setAsync(K key,
V value,
long ttl,
TimeUnit ttlUnit)
Asynchronously puts an entry into this map with a given TTL (time to live) value,
without returning the old value (which is more efficient than
put() ). |
CompletionStage<Void> |
setAsync(K key,
V value,
long ttl,
TimeUnit ttlUnit,
long maxIdle,
TimeUnit maxIdleUnit)
Asynchronously puts an entry into this map with a given TTL (time to live)
value and max idle time value without returning the old value
(which is more efficient than
put() ). |
boolean |
setTtl(K key,
long ttl,
TimeUnit timeunit)
Updates the TTL (time to live) value of the entry specified by
key
with a new TTL value. |
<R> CompletionStage<R> |
submitToKey(K key,
EntryProcessor<K,V,R> entryProcessor)
Applies the user defined
EntryProcessor to the entry mapped by the key . |
<R> CompletionStage<Map<K,R>> |
submitToKeys(Set<K> keys,
EntryProcessor<K,V,R> entryProcessor)
|
boolean |
tryLock(K key)
Tries to acquire the lock for the specified key.
|
boolean |
tryLock(K key,
long time,
TimeUnit timeunit)
Tries to acquire the lock for the specified key.
|
boolean |
tryLock(K key,
long time,
TimeUnit timeunit,
long leaseTime,
TimeUnit leaseTimeunit)
Tries to acquire the lock for the specified key for the specified lease time.
|
boolean |
tryPut(K key,
V value,
long timeout,
TimeUnit timeunit)
Tries to put the given key and value into this map within a specified
timeout value.
|
boolean |
tryRemove(K key,
long timeout,
TimeUnit timeunit)
Tries to remove the entry with the given key from this map
within the specified timeout value.
|
void |
unlock(K key)
Releases the lock for the specified key.
|
Collection<V> |
values()
Returns an immutable collection clone of the values contained in this map.
|
Collection<V> |
values(Predicate<K,V> predicate)
Queries the map based on the specified predicate and returns an immutable
collection of the values of matching entries.
|
getOrDefault
destroy, getDestroyContextForTenant, getName, getPartitionKey, getServiceName
forEach, spliterator
void putAll(@Nonnull Map<? extends K,? extends V> m)
No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.
Interactions with the map store
For each element not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map, which may come at a significant
performance cost. Exceptions thrown by load fail the operation
and are propagated to the caller. The elements which were added
before the exception was thrown will remain in the map, the rest
will not be added.
If write-through persistence mode is configured,
MapStore.store(Object, Object)
is invoked for each element
before the element is added in memory, which may come at a
significant performance cost. Exceptions thrown by store fail the
operation and are propagated to the caller. The elements which
were added before the exception was thrown will remain in the map,
the rest will not be added.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
boolean containsKey(@Nonnull Object key)
true
if this map contains an entry for the specified
key.
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If key
is not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
containsKey
in interface BaseMap<K,V>
containsKey
in interface Map<K,V>
key
- The specified key.true
if this map contains an entry for the specified key.NullPointerException
- if the specified key is null
boolean containsValue(@Nonnull Object value)
containsValue
in interface Map<K,V>
NullPointerException
- if the specified value is null
V get(@Nonnull Object key)
null
if this map does not contain this key.
Warning 1:
This method returns a clone of the original value, so modifying the returned value does not change the actual value in the map. You should put the modified value back to make changes visible to all nodes.
V value = map.get(key); value.updateSomeProperty(); map.put(key, value);
Warning 2:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If value with key
is not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
V put(@Nonnull K key, @Nonnull V value)
Warning 1:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Warning 2:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Note:
Use set(Object, Object)
if you don't need the return value, it's
slightly more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
put
in interface BaseMap<K,V>
put
in interface Map<K,V>
key
- The specified key.value
- The value to associate with the key.key
or null
if there was no mapping for key
.NullPointerException
- if the specified key or value is nullV remove(@Nonnull Object key)
If you don't need the previously mapped value for the removed key, prefer
to use delete(java.lang.Object)
and avoid the cost of serialization and network
transfer.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is removed from the memory, MapStore.delete(Object)
is
called to remove the value from the map store. Exceptions thrown
by delete fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
remove
in interface BaseMap<K,V>
remove
in interface Map<K,V>
key
- Remove the mapping for this key.key
, or null
if there was no mapping for key
.NullPointerException
- if the specified key is nulldelete(Object)
boolean remove(@Nonnull Object key, @Nonnull Object value)
if (map.containsKey(key) && map.get(key).equals(value)) { map.remove(key); return true; } else return false;except that the action is performed atomically.
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is removed from the memory, MapStore.delete(Object)
is
called to remove the value from the map store. Exceptions thrown
by delete fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
remove
in interface BaseMap<K,V>
remove
in interface ConcurrentMap<K,V>
remove
in interface Map<K,V>
key
- The specified key.value
- Remove the key if it has this value.true
if the value was removed.NullPointerException
- if the specified key or value is nullvoid removeAll(@Nonnull Predicate<K,V> predicate)
If this map has index, matching entries will be found via index search, otherwise they will be found by full-scan.
Note that calling this method also removes all entries from caller's Near Cache.
Interactions with the map store
If write-through persistence mode is configured, before a value is
removed from the memory, MapStore.delete(Object)
is called to
remove the value from the map store. Exceptions thrown by delete fail
the operation and are propagated to the caller.
If write-behind persistence mode is configured with write-coalescing
turned off, ReachedMaxSizeException
may be
thrown if the write-behind queue has reached its per-node maximum
capacity.
predicate
- matching entries with this predicate will be removed
from this mapNullPointerException
- if the specified predicate is nullvoid delete(@Nonnull Object key)
Unlike remove(Object)
, this operation does not return
the removed value, which avoids the serialization and network transfer cost of the
returned value. If the removed value will not be used, this operation
is preferred over the remove operation for better performance.
The map will not contain a mapping for the specified key once the call returns.
Warning:
This method breaks the contract of EntryListener. When an entry is removed by delete(), it fires an EntryEvent with a null oldValue.
Also, a listener with predicates will have null values, so only keys can be queried via predicates.
Interactions with the map store
If write-through persistence mode is configured, before the value
is removed from the the memory, MapStore.delete(Object)
is called to remove the value from the map store. Exceptions
thrown by delete fail the operation and are propagated to the
caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
delete
in interface BaseMap<K,V>
key
- key whose mapping is to be removed from the mapClassCastException
- if the key is of an inappropriate type for this map (optional)NullPointerException
- if the specified key is nullremove(Object)
void flush()
Interactions with the map store
Calls MapStore.storeAll(Map)
and/or
MapStore.deleteAll(Collection)
with elements marked dirty.
Please note that this method has effect only if write-behind persistence mode is configured. If the persistence mode is write-through calling this method has no practical effect, but an operation is executed on all partitions wasting resources.
Map<K,V> getAll(@Nullable Set<K> keys)
Warning 1:
The returned map is NOT backed by the original map, so changes to the original map are NOT reflected in the returned map.
Warning 2:
This method uses hashCode
and equals
of the binary form
of the keys
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If any keys are not found in memory, MapLoader.loadAll(java.util.Collection<K>)
is called with the missing keys. Exceptions thrown by
loadAll fail the operation and are propagated to the caller.
keys
- keys to get (keys inside the collection cannot be null)NullPointerException
- if any of the specified
keys are null or if any key or any value returned
from MapLoader.loadAll(java.util.Collection<K>)
is null
.void loadAll(boolean replaceExistingValues)
Interactions with the map store
Calls MapLoader.loadAllKeys()
and with the loaded keys
calls MapLoader.loadAll(java.util.Collection)
on each
partition. Exceptions thrown by loadAllKeys() or loadAll() are
not propagated to the caller.
replaceExistingValues
- when true
, existing values
in the Map will be replaced by those
loaded from the MapLoadervoid loadAll(@Nonnull Set<K> keys, boolean replaceExistingValues)
Interactions with the map store
Calls MapLoader.loadAll(java.util.Collection)
on the
partitions storing the values with the keys. Exceptions thrown by
loadAll() are not propagated to the caller.
keys
- keys of the values entries to load (keys inside the collection cannot be null)replaceExistingValues
- when true
, existing values in the Map will
be replaced by those loaded from the MapLoadervoid clear()
The MAP_CLEARED event is fired for any registered listeners.
See MapClearedListener.mapCleared(MapEvent)
.
To clear the map without removing the items from the map store,
use evictAll()
.
Interactions with the map store
Calls MapStore.deleteAll(Collection)
on each partition
with the keys that the given partition stores. Exceptions thrown
by deleteAll() are not propagated to the caller.
clear
in interface Map<K,V>
evictAll()
CompletionStage<V> getAsync(@Nonnull K key)
CompletionStage
can be converted to a
CompletableFuture
to obtain the value in a blocking way:
CompletionStage future = map.getAsync(key); // do some other stuff, when ready get the result. Object value = future.toCompletableFuture().get();Additionally, the client can register further computation stages to be invoked upon completion of the
CompletionStage
via any of CompletionStage
methods:
// assuming an IMap<String, String>
CompletionStage<String> future = map.getAsync("a");
future.thenAcceptAsync(response -> System.out.println(response));
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If value with key
is not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load
fail
the operation and are propagated to the caller.
key
- the key of the map entryNullPointerException
- if the specified key is nullCompletionStage
CompletionStage<V> putAsync(@Nonnull K key, @Nonnull V value)
CompletionStage
can be converted to a
CompletableFuture
to obtain the value in a blocking way:
CompletionStage<Object> future = map.putAsync(key, value);
// do some other stuff, when ready get the result.
Object oldValue = future.toCompletableFuture().get();
Additionally, the client can register further computation stages to be invoked upon
completion of the CompletionStage
via any of CompletionStage
methods:
// assuming an IMap<String, String>
CompletionStage<String> future = map.putAsync("a", "b");
future.whenCompleteAsync((v, throwable) -> {
if (throwable == null) {
// do something with the old value returned by put operation
} else {
// handle failure
}
});
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Note:
Use setAsync(Object, Object)
if you don't need the return value, it's slightly more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryNullPointerException
- if the specified key or value is nullCompletionStage
,
setAsync(Object, Object)
CompletionStage<V> putAsync(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
CompletionStage future = map.putAsync(key, value, ttl, timeunit); // do some other stuff, when ready get the result Object oldValue = future.toCompletableFuture().get();
CompletionStage.toCompletableFuture().get()
will block until the actual map.put() completes.
If your application requires a timely response,
then you can use Future.get(timeout, timeunit).
try { CompletionStage future = map.putAsync(key, newValue, ttl, timeunit); Object oldValue = future.toCompletableFuture().get(40, TimeUnit.MILLISECOND); } catch (TimeoutException t) { // time wasn't enough }The client can register further computation stages to be invoked upon completion of the
CompletionStage
via any of CompletionStage
methods:
// assuming an IMap<String, String>
CompletionStage<String> future = map.putAsync("a", "b", 5, TimeUnit.MINUTES);
future.thenAccept(oldVal -> System.out.println(oldVal));
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Note:
Use setAsync(Object, Object, long, TimeUnit)
if you don't need the return value, it's slightly
more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key or value is nullCompletionStage
,
setAsync(Object, Object, long, TimeUnit)
CompletionStage<V> putAsync(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that is less than 1 second can lead to unexpected behaviour.
CompletionStage future = map.putAsync(key, value, ttl, timeunit); // do some other stuff, when ready get the result Object oldValue = future.toCompletableFuture().get();
CompletionStage.toCompletableFuture().get()
will block until the actual map.put() completes.
If your application requires a timely response,
then you can use Future.get(timeout, timeunit)
.
try { CompletionStage future = map.putAsync(key, newValue, ttl, timeunit); Object oldValue = future.toCompletableFuture().get(40, TimeUnit.MILLISECOND); } catch (TimeoutException t) { // time wasn't enough }The client can register further computation stages to be invoked upon completion of the
CompletionStage
via any of CompletionStage
methods:
// assuming an IMap<String, String>
CompletionStage<String> future = map.putAsync("a", "b", 5, TimeUnit.MINUTES);
future.thenAcceptAsync(oldValue -> System.out.println(oldValue));
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Note:
Use setAsync(Object, Object, long, TimeUnit)
if you don't need
the return value, it's slightly more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key, value, ttlUnit or maxIdleUnit are null
CompletionStage
,
setAsync(Object, Object, long, TimeUnit)
CompletionStage<Void> putAllAsync(@Nonnull Map<? extends K,? extends V> map)
CompletionStage<Void> future = map.putAllAsync(map);
// do some other stuff, when ready wait for completion
future.toCompletableFuture.get();
CompletionStage.toCompletableFuture.get()
will block until the actual map.putAll(map) operation completes
You can also register further computation stages to be invoked upon
completion of the CompletionStage
via any of CompletionStage
methods:
CompletionStage<Void> future = map.putAllAsync(map);
future.thenRunAsync(() -> System.out.println("All the entries are added"));
No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.
Interactions with the map store
For each element not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map, which may come at a significant
performance cost. Exceptions thrown by load fail the operation
and are propagated to the caller. The elements which were added
before the exception was thrown will remain in the map, the rest
will not be added.
If write-through persistence mode is configured,
MapStore.store(Object, Object)
is invoked for each element
before the element is added in memory, which may come at a
significant performance cost. Exceptions thrown by store fail the
operation and are propagated to the caller. The elements which
were added before the exception was thrown will remain in the map,
the rest will not be added.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
map
- mappings to be stored in this mapCompletionStage
CompletionStage<Void> setAsync(@Nonnull K key, @Nonnull V value)
CompletionStage<Void> future = map.setAsync(key, value);
// do some other stuff, when ready wait for completion
future.toCompletableFuture().get();
CompletionStage.toCompletableFuture().get()
will block until the actual map.set() operation completes.
You can also register further computation stages to be invoked upon
completion of the CompletionStage
via any of CompletionStage
methods:
CompletionStage<Void> future = map.setAsync("a", "b");
future.thenRunAsync(() -> System.out.println("Value is now set to b."));
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryNullPointerException
- if the specified key or value is nullCompletionStage
CompletionStage<Void> setAsync(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
put()
).
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
CompletionStage<Void> future = map.setAsync(key, value, ttl, timeunit); // do some other stuff, when you want to make sure set operation is complete: future.toCompletableFuture().get();
CompletionStage.toCompletableFuture().get()
will block until the actual map set operation completes.
If your application requires a timely response,
then you can use CompletionStage.toCompletableFuture().get(long, TimeUnit)
.
try { CompletionStage<Void> future = map.setAsync(key, newValue, ttl, timeunit); future.toCompletableFuture().get(40, TimeUnit.MILLISECOND); } catch (TimeoutException t) { // time wasn't enough }You can also register further computation stages to be invoked upon completion of the
CompletionStage
via any of CompletionStage
methods:
CompletionStage<Void> future = map.setAsync("a", "b", 5, TimeUnit.MINUTES); future.thenRunAsync(() -> System.out.println("done"));
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key, value, ttlUnitCompletionStage
CompletionStage<Void> setAsync(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
put()
).
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that less than 1 second can lead to unexpected behaviour.
CompletionStage<Void> future = map.setAsync(key, value, ttl, timeunit); // do some other stuff, when you want to make sure set operation is complete: future.toCompletableFuture().get();
CompletionStage.toCompletableFuture().get()
will block until the actual map set operation
completes. If your application requires a timely response,
then you can use CompletionStage.toCompletableFuture().get(long, TimeUnit)
.
try { CompletionStage<Void> future = map.setAsync(key, newValue, ttl, timeunit); future.toCompletableFuture().get(40, TimeUnit.MILLISECOND); } catch (TimeoutException t) { // time wasn't enough }You can also register further computation stages to be invoked upon completion of the
CompletionStage
via any of CompletionStage
methods:
CompletionStage<Void> future = map.setAsync("a", "b", 5, TimeUnit.MINUTES); future.thenRunAsync(() -> System.out.println("Done"));
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- the key of the map entryvalue
- the new value of the map entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key, value, ttlUnit or maxIdleUnit are null
CompletionStage
CompletionStage<V> removeAsync(@Nonnull K key)
CompletionStage
on which the caller can register further computation stages to be invoked
upon remove operation completion or block waiting for the operation to
complete using one of blocking ways to wait on
CompletionStage.toCompletableFuture()
.
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If write-through persistence mode is configured, before the value
is removed from the the memory, MapStore.delete(Object)
is called to remove the value from the map store. Exceptions
thrown by delete fail the operation and are propagated to the
caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- The key of the map entry to removeCompletionStage
from which the value removed from the map can be retrievedNullPointerException
- if the specified key is null
CompletionStage
boolean tryRemove(@Nonnull K key, long timeout, @Nonnull TimeUnit timeunit)
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If write-through persistence mode is configured, before the value
is removed from the the memory, MapStore.delete(Object)
is called to remove the value from the map store. Exceptions
thrown by delete fail the operation and are propagated to the
caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entrytimeout
- maximum time to wait for acquiring the lock for the keytimeunit
- time unit for the timeouttrue
if the remove is successful, false
otherwiseNullPointerException
- if the specified key is null
boolean tryPut(@Nonnull K key, @Nonnull V value, long timeout, @Nonnull TimeUnit timeunit)
Warning:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entrytimeout
- maximum time to waittimeunit
- time unit for the timeouttrue
if the put is successful, false
otherwiseNullPointerException
- if the specified key or value is null
V put(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Warning 3:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Note:
Use set(Object, Object, long, TimeUnit)
if you don't need the
return value, it's slightly more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
put
in interface BaseMap<K,V>
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key or value is null
V put(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that less than 1 second can lead to unexpected behaviour.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Warning 3:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Note:
Use set(Object, Object, long, TimeUnit)
if you don't need the
return value, it's slightly more efficient.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key, value, ttlUnit or maxIdleUnit are null
void putTransient(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
put(Object, Object, long, TimeUnit)
except that the map store, if defined, will not be called to
load/store/persist the entry.
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to next closest second value.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key or value is null
void putTransient(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
put(Object, Object, long, TimeUnit)
except that the map
store, if defined, will not be called to load/store/persist the entry.
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that less than 1 second can lead to unexpected behaviour.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to next closest second value.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key
, value
, ttlUnit
or
maxIdleUnit
are null
V putIfAbsent(@Nonnull K key, @Nonnull V value)
if (!map.containsKey(key)) return map.put(key, value); else return map.get(key);except that the action is performed atomically.
Note:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Also, this method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
putIfAbsent
in interface BaseMap<K,V>
putIfAbsent
in interface ConcurrentMap<K,V>
putIfAbsent
in interface Map<K,V>
key
- The specified key.value
- The value to associate with the key when there is no previous value.NullPointerException
- if the specified key
or value
is null
V putIfAbsent(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Warning 3:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key
or value
is null
V putIfAbsent(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that less than 1 second can lead to unexpected behaviour.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Warning 3:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If no value is found with key
in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map. Exceptions thrown by load fail
the operation and are propagated to the caller.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key
, value
, ttlUnit
or
maxIdleUnit
are null
boolean replace(@Nonnull K key, @Nonnull V oldValue, @Nonnull V newValue)
if (map.containsKey(key) && map.get(key).equals(oldValue)) { map.put(key, newValue); return true; } else return false;except that the action is performed atomically.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method may return false
even if the operation succeeds.
Background: If the partition owner for given key goes down after successful
value replace, but before the executing node retrieved the invocation
result response, then the operation is retried. The invocation retry fails
because the value is already updated and the result of such replace call
returns false
. Hazelcast doesn't guarantee exactly once invocation.
Interactions with the map store
If value with key
is not found in memory,
MapLoader.load(Object)
is invoked to load the value from the map
store backing the map.
If write-through persistence mode is configured, before the value is
stored in memory, MapStore.store(Object, Object)
is called to
write the value into the map store. Exceptions thrown by the store fail
the operation and are propagated to the caller.
If write-behind persistence mode is configured with write-coalescing
turned off, ReachedMaxSizeException
may be
thrown if the write-behind queue has reached its per-node maximum capacity.
replace
in interface BaseMap<K,V>
replace
in interface ConcurrentMap<K,V>
replace
in interface Map<K,V>
key
- The specified key.oldValue
- Replace the key value if it is the old value.newValue
- The new value to replace the old value.true
if the value was replaced.NullPointerException
- if any of the specified parameters are null
V replace(@Nonnull K key, @Nonnull V value)
if (map.containsKey(key)) { return map.put(key, value); } else return null;except that the action is performed atomically.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
This method returns a clone of the previous value, not the original (identically equal) value previously put into the map.
Interactions with the map store
If value with key
is not found in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map.
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
replace
in interface BaseMap<K,V>
replace
in interface ConcurrentMap<K,V>
replace
in interface Map<K,V>
key
- The specified key.value
- The value to replace the previous value.key
, or null
if there was no mapping for key
.NullPointerException
- if the specified key or value is null
void set(@Nonnull K key, @Nonnull V value)
put()
).
Warning 1:
This method breaks the contract of EntryListener. When an entry is updated by set(), it fires an EntryEvent with a null oldValue.
Warning 2:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
set
in interface BaseMap<K,V>
key
- key of the entryvalue
- value of the entryNullPointerException
- if the specified key or value is null
void set(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit)
put()
).
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLNullPointerException
- if the specified key or value is null
void set(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit, long maxIdle, @Nonnull TimeUnit maxIdleUnit)
put()
).
The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the MaxIdle is 0, then the entry lives forever. If the MaxIdle is negative, then the MaxIdle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The MaxIdle that less than 1 second can lead to unexpected behaviour.
Warning 1:
This method uses hashCode
and equals
of the binary form
of the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
Warning 2:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
Interactions with the map store
If write-through persistence mode is configured, before the value
is stored in memory, MapStore.store(Object, Object)
is
called to write the value into the map store. Exceptions thrown
by the store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
key
- key of the entryvalue
- value of the entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)ttlUnit
- time unit for the TTLmaxIdle
- maximum time for this entry to stay idle in the map.
(0 means infinite, negative means map config default)maxIdleUnit
- time unit for the Max-IdleNullPointerException
- if the specified key, value, ttlUnit or maxIdleUnit are null
void setAll(@Nonnull Map<? extends K,? extends V> map)
putAll()
).
This method breaks the contract of EntryListener. EntryEvent of all the updated entries will have null oldValue even if they exist previously.
No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.
Interactions with the map store
If write-through persistence mode is configured,
MapStore.store(Object, Object)
is invoked for each element
before the element is added in memory, which may come at a
significant performance cost. Exceptions thrown by store fail the
operation and are propagated to the caller. The elements which
were added before the exception was thrown will remain in the map,
the rest will not be added.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
CompletionStage<Void> setAllAsync(@Nonnull Map<? extends K,? extends V> map)
CompletionStage<Void> future = map.setAllAsync(map);
// do some other stuff, when ready wait for completion
future.toCompletableFuture.get();
CompletionStage.toCompletableFuture.get()
will block until the actual map.setAll(map) operation completes
You can also register further computation stages to be invoked upon
completion of the CompletionStage
via any of CompletionStage
methods:
CompletionStage<Void> future = map.setAllAsync(map);
future.thenRunAsync(() -> System.out.println("All the entries are set"));
This method breaks the contract of EntryListener. EntryEvent of all the updated entries will have null oldValue even if they exist previously.
No atomicity guarantees are given. It could be that in case of failure some of the key/value-pairs get written, while others are not.
Interactions with the map store
If write-through persistence mode is configured,
MapStore.store(Object, Object)
is invoked for each element
before the element is added in memory, which may come at a
significant performance cost. Exceptions thrown by store fail the
operation and are propagated to the caller. The elements which
were added before the exception was thrown will remain in the map,
the rest will not be added.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
map
- mappings to be stored in this mapCompletionStage
void lock(@Nonnull K key)
If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.
You get a lock whether the value is present in the map or not. Other
threads (possibly on other systems) would block on their invoke of
lock()
until the non-existent key is unlocked. If the lock
holder introduces the key to the map, the put()
operation
is not blocked. If a thread not holding a lock on the non-existent key
tries to introduce the key while a lock exists on the non-existent key,
the put()
operation blocks until it is unlocked.
Scope of the lock is this map only. Acquired lock is only for the key in this map.
Locks are re-entrant so if the key is locked N times then it should be unlocked N times before another thread can acquire it.
There is no lock timeout on this method. Locks will be held infinitely.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- key to lockNullPointerException
- if the specified key is null
void lock(@Nonnull K key, long leaseTime, @Nullable TimeUnit timeUnit)
After lease time, the lock will be released.
If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.
Scope of the lock is this map only. Acquired lock is only for the key in this map.
Locks are re-entrant, so if the key is locked N times then it should be unlocked N times before another thread can acquire it.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key to lockleaseTime
- time to wait before releasing the locktimeUnit
- unit of time to specify lease timeNullPointerException
- if the specified key is null
IllegalArgumentException
- if the leaseTime is not positiveboolean isLocked(@Nonnull K key)
If the lock is acquired then returns true, else returns false.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key that is checked for locktrue
if lock is acquired, false
otherwiseNullPointerException
- if the specified key is null
boolean tryLock(@Nonnull K key)
If the lock is not available then the current thread doesn't wait and returns false immediately.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key to locktrue
if lock is acquired, false
otherwiseNullPointerException
- if the specified key is null
boolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit) throws InterruptedException
If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- key to lock in this maptime
- maximum time to wait for the locktimeunit
- time unit of the time
argumenttrue
if the lock was acquired, false
if the waiting time
elapsed before the lock was acquiredNullPointerException
- if the specified key is null
InterruptedException
- if interrupted while trying to acquire the lockboolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit, long leaseTime, @Nullable TimeUnit leaseTimeunit) throws InterruptedException
After lease time, the lock will be released.
If the lock is not available, then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- key to lock in this maptime
- maximum time to wait for the locktimeunit
- time unit of the time
argumentleaseTime
- time to wait before releasing the lockleaseTimeunit
- unit of time to specify lease timetrue
if the lock was acquired, false
if the waiting time
elapsed before the lock was acquiredNullPointerException
- if the specified key is null
InterruptedException
- if interrupted while trying to acquire the lockvoid unlock(@Nonnull K key)
If the current thread is the holder of this lock, then the hold
count is decremented. If the hold count is zero, then the lock
is released. If the current thread is not the holder of this
lock, then IllegalMonitorStateException
is thrown.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key to unlockNullPointerException
- if the specified key is null
IllegalMonitorStateException
- if the current thread does not hold this lockvoid forceUnlock(@Nonnull K key)
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key to unlockNullPointerException
- if the specified key is null
UUID addLocalEntryListener(@Nonnull MapListener listener)
MapListener
for this map. To receive an event, you should
implement a corresponding MapListener
sub-interface for that event.
Note that entries in distributed map are partitioned across
the cluster members; each member owns and manages the some portion of the
entries. Owned entries are called local entries. This
listener will be listening for the events of local entries. Let's say
your cluster has member1 and member2. On member2 you added a local listener and from
member1, you call map.put(key2, value2)
.
If the key2 is owned by member2 then the local listener will be
notified for the add/update event. Also note that entries can migrate to
other nodes for load balancing and/or membership change.
listener
- MapListener
for this mapUnsupportedOperationException
- if this operation is not supported, for example on a Hazelcast clientNullPointerException
- if the listener is null
localKeySet()
,
MapListener
UUID addLocalEntryListener(@Nonnull MapListener listener, @Nonnull Predicate<K,V> predicate, boolean includeValue)
MapListener
for this map.
To receive an event, you should implement a corresponding MapListener
sub-interface for that event.
The listener will get notified for map events filtered by the given predicate.
listener
- MapListener
for this mappredicate
- predicate for filtering entriesincludeValue
- true
if EntryEvent
should contain the valueUnsupportedOperationException
- if this operation isn't supported, for example on a Hazelcast clientNullPointerException
- if the listener
or predicate
is null
MapListener
UUID addLocalEntryListener(@Nonnull MapListener listener, @Nonnull Predicate<K,V> predicate, @Nullable K key, boolean includeValue)
The added listener will only be listening for the events (add/remove/update/evict) of the locally owned entries. The listener will get notified for map add/remove/update/evict events filtered by the given predicate.
listener
- MapListener
for this mappredicate
- predicate for filtering entrieskey
- key to listen forincludeValue
- true
if EntryEvent
should contain the valueNullPointerException
- if the listener is null
NullPointerException
- if the predicate is null
MapListener
String addInterceptor(@Nonnull MapInterceptor interceptor)
Added interceptor will intercept operations and execute user defined methods. They will cancel operations if the user defined method throws an exception.
interceptor
- map interceptorboolean removeInterceptor(@Nonnull String id)
id
- registration ID of the map interceptortrue
if registration is removed, false
otherwiseUUID addEntryListener(@Nonnull MapListener listener, boolean includeValue)
MapListener
for this map.
To receive an event, you should implement a corresponding MapListener
sub-interface for that event.
listener
- MapListener
for this mapincludeValue
- true
if EntryEvent
should contain the valueNullPointerException
- if the specified listener is null
MapListener
boolean removeEntryListener(@Nonnull UUID id)
Returns silently if there is no such listener added before.
id
- ID of registered listenerUUID addPartitionLostListener(@Nonnull MapPartitionLostListener listener)
The method returns a register ID. This ID is needed to remove the
MapPartitionLostListener
using the
removePartitionLostListener(UUID)
method.
There is no check for duplicate registrations, so if you register the listener twice, you will receive events twice.
Warning 1:
Please see PartitionLostListener
for weaknesses.
Warning 2:
Listeners registered from HazelcastClient may miss some of the map partition lost events due to design limitations.
listener
- the added MapPartitionLostListenerNullPointerException
- if listener is null
removePartitionLostListener(UUID)
,
PartitionLostListener
boolean removePartitionLostListener(@Nonnull UUID id)
Returns silently if there is no such listener was added before.
id
- ID of registered listenerNullPointerException
- if id
is null
UUID addEntryListener(@Nonnull MapListener listener, @Nonnull K key, boolean includeValue)
MapListener
for this map. To receive an event, you should
implement a corresponding MapListener
sub-interface for that event.
Warning:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
listener
- MapListener
for this mapkey
- key to listen forincludeValue
- true
if EntryEvent
should contain the valueNullPointerException
- if the specified listener is null
NullPointerException
- if the specified key is null
MapListener
UUID addEntryListener(@Nonnull MapListener listener, @Nonnull Predicate<K,V> predicate, boolean includeValue)
MapListener
for this map.
To receive an event, you should implement a corresponding MapListener
sub-interface for that event.
listener
- the added continuous MapListener
for this mappredicate
- predicate for filtering entriesincludeValue
- true
if EntryEvent
should contain the valueNullPointerException
- if the specified listener
or predicate
is null
MapListener
UUID addEntryListener(@Nonnull MapListener listener, @Nonnull Predicate<K,V> predicate, @Nullable K key, boolean includeValue)
MapListener
for this map.
To receive an event, you should implement a corresponding MapListener
sub-interface for that event.
listener
- the continuous MapListener
for this mappredicate
- predicate for filtering entrieskey
- key to listen forincludeValue
- true
if EntryEvent
should contain the valueNullPointerException
- if the specified listener
or predicate
is null
MapListener
EntryView<K,V> getEntryView(@Nonnull K key)
EntryView
for the specified key.
Warning 1:
This method returns a clone of original mapping, modifying the returned value does not change the actual value in the map. One should put modified value back to make changes visible to all nodes.
Warning 2:
This method uses hashCode
and equals
of the binary form of
the key
, not the actual implementations of hashCode
and equals
defined in the key
's class.
key
- the key of the entryEntryView
of the specified keyNullPointerException
- if the specified key is null
EntryView
boolean evict(@Nonnull K key)
If a MapStore
is defined for this map, then the entry is
not deleted from the underlying MapStore
, evict only
removes the entry from the memory. Use delete(Object)
or
remove(Object)
if MapStore.delete(Object)
needs
to be called.
Warning:
This method uses hashCode
and equals
of the
binary form of the key
, not the actual implementations of
hashCode
and equals
defined in the key
's
class.
key
- the specified key to evict from this maptrue
if the key is evicted, false
otherwiseNullPointerException
- if the specified key is null
delete(Object)
,
remove(Object)
void evictAll()
If a MapStore
is defined for this map, deleteAll is
not called by this method. If you do want to
MapStore.deleteAll(Collection)
to be called use the
clear()
method.
The EVICT_ALL event is fired for any registered listeners.
See MapEvictedListener.mapEvicted(MapEvent)
.
clear()
@Nonnull Set<K> keySet()
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
keySet
in interface BaseMap<K,V>
keySet
in interface Map<K,V>
QueryResultSizeExceededException
- if query result size limit is exceededClusterProperty.QUERY_RESULT_SIZE_LIMIT
@Nonnull Collection<V> values()
Warning:
The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
values
in interface BaseMap<K,V>
values
in interface Map<K,V>
QueryResultSizeExceededException
- if query result size limit is exceededClusterProperty.QUERY_RESULT_SIZE_LIMIT
@Nonnull Set<Map.Entry<K,V>> entrySet()
Set
clone of the mappings contained in this map.
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
entrySet
in interface Map<K,V>
QueryResultSizeExceededException
- if query result size limit is exceededClusterProperty.QUERY_RESULT_SIZE_LIMIT
Set<K> keySet(@Nonnull Predicate<K,V> predicate)
Set
clone of the keys of matching entries.
Specified predicate runs on all members in parallel.
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
keySet
in interface BaseMap<K,V>
predicate
- specified query criteriaQueryResultSizeExceededException
- if query result size limit is exceededNullPointerException
- if the predicate is null
ClusterProperty.QUERY_RESULT_SIZE_LIMIT
Set<Map.Entry<K,V>> entrySet(@Nonnull Predicate<K,V> predicate)
Specified predicate runs on all members in parallel.
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
predicate
- specified query criteriaQueryResultSizeExceededException
- if query result size limit is exceededNullPointerException
- if the predicate is null
ClusterProperty.QUERY_RESULT_SIZE_LIMIT
Collection<V> values(@Nonnull Predicate<K,V> predicate)
Specified predicate runs on all members in parallel.
Warning:
The collection is NOT backed by the map, so changes to the map are NOT reflected in the collection.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
values
in interface BaseMap<K,V>
predicate
- specified query criteriaQueryResultSizeExceededException
- if query result size limit is exceededNullPointerException
- if the predicate is null
ClusterProperty.QUERY_RESULT_SIZE_LIMIT
Set<K> localKeySet()
Each key in this map is owned and managed by a specific member in the cluster.
Note that ownership of these keys might change over time so that key ownerships can be almost evenly distributed in the cluster.
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
QueryResultSizeExceededException
- if query result size limit is exceededClusterProperty.QUERY_RESULT_SIZE_LIMIT
Set<K> localKeySet(@Nonnull Predicate<K,V> predicate)
Each key in this map is owned and managed by a specific member in the cluster.
Note that ownership of these keys might change over time so that key ownerships can be almost evenly distributed in the cluster.
Warning:
The set is NOT backed by the map, so changes to the map are NOT reflected in the set.
This method is always executed by a distributed query,
so it may throw a QueryResultSizeExceededException
if ClusterProperty.QUERY_RESULT_SIZE_LIMIT
is configured.
predicate
- specified query criteriaQueryResultSizeExceededException
- if query result size limit is exceededClusterProperty.QUERY_RESULT_SIZE_LIMIT
default void addIndex(IndexType type, String... attributes)
type
- Index type.attributes
- Attributes to be indexed.addIndex(IndexConfig)
void addIndex(IndexConfig indexConfig)
Let's say your map values are Employee objects.
public class Employee implements Serializable { private boolean active = false; private int age; private String name = null; // other fields // getters setter }If you are querying your values mostly based on age and active then you may consider indexing these fields.
IMap imap = Hazelcast.getMap("employees"); imap.addIndex(new IndexConfig(IndexType.SORTED, "age")); // Sorted index for range queries imap.addIndex(new IndexConfig(IndexType.HASH, "active")); // Hash index for equality predicatesIndex attribute should either have a getter method or be public. You should also make sure to add the indexes before adding entries to this map.
Time to Index
Indexing time is executed in parallel on each partition by operation threads. The Map is not blocked during this operation.
The time taken in proportional to the size of the Map and the number Members.
Searches while indexes are being built
Until the index finishes being created, any searches for the attribute will use a full Map scan, thus avoiding using a partially built index and returning incorrect results.
indexConfig
- Index configuration.LocalMapStats getLocalMapStats()
LocalMapStats are the statistics for the local portion of this distributed map and contains information such as ownedEntryCount backupEntryCount, lastUpdateTime, lockedEntryCount.
Since this stats are only for the local portion of this map, if you need the cluster-wide MapStats then you need to get the LocalMapStats from all members of the cluster and combine them.
It's guaranteed that the returned LocalMapStats
instance contains
an up-to-date statistics. But over the time some parts of the returned
instance may become stale while others may be updated. To obtain a fresh
up-to-date instance invoke the method one more time.
<R> R executeOnKey(@Nonnull K key, @Nonnull EntryProcessor<K,V,R> entryProcessor)
EntryProcessor
to the entry mapped by the key
.
Returns the object which is the result of the EntryProcessor.process(Map.Entry)
method.
The EntryProcessor
may implement the Offloadable
and ReadOnly
interfaces.
If the EntryProcessor implements the Offloadable
interface, the processing will be offloaded to the given
ExecutorService, allowing unblocking of the partition-thread, which means that other partition-operations
may proceed. The key will be locked for the time-span of the processing in order to not generate a write-conflict.
In this case the threading looks as follows:
If the EntryProcessor implements only ReadOnly without implementing Offloadable, the processing unit will not be offloaded, however, the EntryProcessor will not wait for the lock to be acquired, since the EP will not do any modifications.
Using offloading is useful if the EntryProcessor encompasses heavy logic that may stall the partition-thread.
If the EntryProcessor implements ReadOnly and modifies the entry it is processing, an UnsupportedOperationException will be thrown.
Offloading will not be applied to backup partitions. It is possible to initialize the entry backup processor with some input provided by the EntryProcessor in the EntryProcessor.getBackupProcessor() method. The input allows providing context to the entry backup processor, for example the "delta", so that the entry backup processor does not have to calculate the "delta" but it may just apply it.
See submitToKey(Object, EntryProcessor)
for an async version of this method.
Interactions with the map store
If value with key
is not found in memory,
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map.
If the entryProcessor updates the entry and write-through
persistence mode is configured, before the value is stored
in memory, MapStore.store(Object, Object)
is called to
write the value into the map store.
If the entryProcessor updates the entry's value to null value and
write-through persistence mode is configured, before the value is
removed from the memory, MapStore.delete(Object)
is
called to delete the value from the map store.
Any exceptions thrown by the map store fail the operation and are propagated to the caller.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
R
- the entry processor return typeEntryProcessor.process(Map.Entry)
NullPointerException
- if the specified key is null
Offloadable
,
ReadOnly
<R> Map<K,R> executeOnKeys(@Nonnull Set<K> keys, @Nonnull EntryProcessor<K,V,R> entryProcessor)
EntryProcessor
to the entries mapped by the collection of keys.
The operation is not lock-aware. The EntryProcessor
will process the entries no matter if the keys are
locked or not. For more details check Entry Processing section on IMap
documentation.
Interactions with the map store
For each entry not found in memory MapLoader.load(Object)
is invoked to load the value from the map store backing the map.
If write-through persistence mode is configured, for each entry
updated by the entryProcessor, before the updated value is stored
in memory, MapStore.store(Object, Object)
is called to
write the value into the map store.
If write-through persistence mode is configured, for each entry
updated to null value, before the value is removed from the
memory, MapStore.delete(Object)
is called to delete the
value from the map store.
Any exceptions thrown by the map store fail the operation and are propagated to the caller. If an exception happened, the operation might already succeeded on some of the keys.
If write-behind persistence mode is
configured with write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
Performance note
Keep the state of entryProcessor
small, it will be serialized and one copy will be sent to each member.
Additionally, the backup
processor will also be serialized once for each affected partition and
sent to each backup. For example, in this usage the entire additions
map will be duplicated once for each member and once for each
partition and backup:
HashMap additions = ...;
iMap.executeOnKeys(map.keySet(), entry -> {
Integer updateBy = additions.get(entry.getKey());
entry.setValue(entry.getValue() + updateBy);
return null;
});
R
- the entry processor return typekeys
- The keys to execute the entry processor on. Can be empty, in
that case it's a local no-opEntryProcessor.process(Map.Entry)
NullPointerException
- if there's null element in keys
<R> CompletionStage<Map<K,R>> submitToKeys(@Nonnull Set<K> keys, @Nonnull EntryProcessor<K,V,R> entryProcessor)
R
- return type for entry processorkeys
- the keys to execute the entry processor on. Can be empty, in
that case it's a local no-opentryProcessor
- the processor to process the keysCompletionStage
<R> CompletionStage<R> submitToKey(@Nonnull K key, @Nonnull EntryProcessor<K,V,R> entryProcessor)
EntryProcessor
to the entry mapped by the key
.
Returns immediately with a CompletionStage
representing that task.
EntryProcessor is not cancellable, so calling CompletionStage.cancel() method won't cancel the operation of EntryProcessor.
The EntryProcessor may implement the Offloadable and ReadOnly interfaces.
If the EntryProcessor implements the Offloadable interface the processing will be offloaded to the given ExecutorService allowing unblocking the partition-thread, which means that other partition-operations may proceed. The key will be locked for the time-span of the processing in order to not generate a write-conflict. In this case the threading looks as follows:
If the EntryProcessor implements only ReadOnly without implementing Offloadable the processing unit will not be offloaded, however, the EntryProcessor will not wait for the lock to be acquired, since the EP will not do any modifications.
If the EntryProcessor implements ReadOnly and modifies the entry it is processing a UnsupportedOperationException will be thrown.
Using offloading is useful if the EntryProcessor encompasses heavy logic that may stall the partition-thread.
Offloading will not be applied to backup partitions. It is possible to initialize the entry backup processor with some input provided by the EntryProcessor in the EntryProcessor.getBackupProcessor() method. The input allows providing context to the entry backup processor - for example the "delta" so that the entry backup processor does not have to calculate the "delta" but it may just apply it.
See executeOnKey(Object, EntryProcessor)
for sync version of this method.
Interactions with the map store
If value with key
is not found in memory
MapLoader.load(Object)
is invoked to load the value from
the map store backing the map.
If the entryProcessor updates the entry and write-through
persistence mode is configured, before the value is stored
in memory, MapStore.store(Object, Object)
is called to
write the value into the map store.
If the entryProcessor updates the entry's value to null value and
write-through persistence mode is configured, before the value is
removed from the memory, MapStore.delete(Object)
is
called to delete the value from the map store.
Any exception thrown by the map store fail the operation.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
R
- return type for entry processorkey
- key to be processedentryProcessor
- processor to process the keyOffloadable
,
ReadOnly
,
CompletionStage
<R> Map<K,R> executeOnEntries(@Nonnull EntryProcessor<K,V,R> entryProcessor)
EntryProcessor
to the all entries in the map.
Returns the results mapped by each key in the map.
The operation is not lock-aware. The EntryProcessor
will process the entries no matter if the keys are
locked or not. For more details check Entry Processing section on IMap
documentation.
Interactions with the map store
For each entry not found in memory MapLoader.load(Object)
is invoked to load the value from the map store backing the map.
If write-through persistence mode is configured, for each entry
updated by the entryProcessor, before the updated value is stored
in memory, MapStore.store(Object, Object)
is called to
write the value into the map store.
If write-through persistence mode is configured, for each entry
updated to null value, before the value is removed from the
memory, MapStore.delete(Object)
is called to delete the
value from the map store.
Any exceptions thrown by the map store fail the operation and are propagated to the caller. If an exception happened, the operation might already succeeded on some of the keys.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
R
- return type for entry processorentryProcessor
- processor to process the keys<R> Map<K,R> executeOnEntries(@Nonnull EntryProcessor<K,V,R> entryProcessor, @Nonnull Predicate<K,V> predicate)
EntryProcessor
to the entries in the map which satisfy provided predicate.
Returns the results mapped by each key in the map.
The operation is not lock-aware. The EntryProcessor
will process the entries no matter if the keys are
locked or not. For more details check Entry Processing section on IMap
documentation.
Interactions with the map store
For each entry not found in memory MapLoader.load(Object)
is invoked to load the value from the map store backing the map.
If write-through persistence mode is configured, for each entry
updated by the entryProcessor, before the updated value is stored
in memory, MapStore.store(Object, Object)
is called to
write the value into the map store.
If write-through persistence mode is configured, for each entry
updated to null value, before the value is removed from the
memory, MapStore.delete(Object)
is called to delete the
value from the map store.
Any exceptions thrown by the map store fail the operation and are propagated to the caller. If an exception happened, the operation might already succeeded on some of the keys.
If write-behind persistence mode is configured with
write-coalescing turned off,
ReachedMaxSizeException
may be thrown
if the write-behind queue has reached its per-node maximum
capacity.
R
- return type for entry processorentryProcessor
- processor to process the keyspredicate
- predicate to filter the entries with<R> R aggregate(@Nonnull Aggregator<? super Map.Entry<K,V>,R> aggregator)
Fast-Aggregations are the successor of the Map-Reduce Aggregators. They are equivalent to the Map-Reduce Aggregators in most of the use-cases, but instead of running on the Map-Reduce engine they run on the Query infrastructure. Their performance is tens to hundreds times better due to the fact that they run in parallel for each partition and are highly optimized for speed and low memory consumption.
R
- type of the resultaggregator
- aggregator to aggregate the entries with<R> R aggregate(@Nonnull Aggregator<? super Map.Entry<K,V>,R> aggregator, @Nonnull Predicate<K,V> predicate)
Fast-Aggregations are the successor of the Map-Reduce Aggregators. They are equivalent to the Map-Reduce Aggregators in most of the use-cases, but instead of running on the Map-Reduce engine they run on the Query infrastructure. Their performance is tens to hundreds times better due to the fact that they run in parallel for each partition and are highly optimized for speed and low memory consumption.
R
- type of the resultaggregator
- aggregator to aggregate the entries withpredicate
- predicate to filter the entries with<R> Collection<R> project(@Nonnull Projection<? super Map.Entry<K,V>,R> projection)
R
- type of the resultprojection
- projection to transform the entries with (may return null)<R> Collection<R> project(@Nonnull Projection<? super Map.Entry<K,V>,R> projection, @Nonnull Predicate<K,V> predicate)
R
- type of the resultprojection
- projection to transform the entries with (may return null)predicate
- predicate to filter the entries withQueryCache<K,V> getQueryCache(@Nonnull String name)
QueryCache
instance for the supplied name
or null.
If there is a previously created QueryCache
with the supplied name
or if a declarative
configuration exists for the supplied name
this method returns or creates the instance respectively,
otherwise returns null.
name
- the name of QueryCache
QueryCache
instance or null if there is no corresponding QueryCacheConfig
NullPointerException
- if the specified name
is null
QueryCache
QueryCache<K,V> getQueryCache(@Nonnull String name, @Nonnull Predicate<K,V> predicate, boolean includeValue)
IMap
according to the supplied parameters.
If there is a previously created QueryCache
with the supplied name
, this method returns that
QueryCache
and ignores predicate
and includeValue
parameters. Otherwise it creates and returns
a new QueryCache
instance.
Also note that if there exists a QueryCacheConfig
for the supplied
name
, predicate
and includeValue
parameters will overwrite corresponding ones
in QueryCacheConfig
.
name
- the name of QueryCache
predicate
- the predicate for filtering entriesincludeValue
- true
if this QueryCache
is allowed to cache values of entries, otherwise false
QueryCache
instance with the supplied name
NullPointerException
- if the specified name
or predicate
is null
QueryCache
QueryCache<K,V> getQueryCache(@Nonnull String name, @Nonnull MapListener listener, @Nonnull Predicate<K,V> predicate, boolean includeValue)
IMap
according to
the supplied parameters.
If there is a previously created QueryCache
with the supplied
name
, this method returns that QueryCache
and ignores
listener
, predicate
and includeValue
parameters.
Otherwise it creates and returns a new QueryCache
instance.
Also note that if there exists a
QueryCacheConfig
for the
supplied name
, listener
,predicate
and
includeValue
parameters will overwrite corresponding ones in
QueryCacheConfig
.
name
- the name of QueryCache
listener
- the MapListener
which will be used to listen this QueryCache
predicate
- the predicate for filtering entriesincludeValue
- true
if this QueryCache
is allowed to cache values of
entries, otherwise false
QueryCache
instance with the supplied name
NullPointerException
- if the specified name
or listener
or predicate
is null
QueryCache
boolean setTtl(@Nonnull K key, long ttl, @Nonnull TimeUnit timeunit)
key
with a new TTL value.
New TTL value is valid starting from the time this operation is invoked,
not since the time the entry was created.
If the entry does not exist or is already expired, this call has no effect.
The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).
If there is no entry with key key
or is already expired, this
call makes no changes to entries stored in this map.
Warning:
Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
key
- the key of the map entryttl
- maximum time for this entry to stay in the map (0 means infinite, negative
means map config default)timeunit
- time unit for the TTLtrue
if the entry exists and its ttl value is changed, false
otherwiseNullPointerException
- if the specified key
or timeunit
is null
.V computeIfPresent(@Nonnull K key, @Nonnull BiFunction<? super K,? super V,? extends V> remappingFunction)
If the supplied remappingFunction
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in multiple round-trips between hazelcast nodes, and possibly a livelock.
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent to the server which owns the key. This results in a single remote call. Also, the function would have exclusive access to the map entry during its execution. Note that in this case, the function class must be deployed on all the servers (either physically or via user-code-deployment).
When this method is invoked using a hazelcast-client instance, the remappingFunction
is always executed locally
computeIfPresent
in interface ConcurrentMap<K,V>
computeIfPresent
in interface Map<K,V>
V computeIfAbsent(@Nonnull K key, @Nonnull Function<? super K,? extends V> mappingFunction)
If the supplied mappingFunction
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in two round-trips between hazelcast nodes.
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent to the server which owns the key. This results in a single remote call. Also, the function would have exclusive access to the map entry during its execution. Note that in this case, the function class must be deployed on all the servers (either physically or via user-code-deployment).
When this method is invoked using a hazelcast-client instance, the mappingFunction
is always executed locally
computeIfAbsent
in interface ConcurrentMap<K,V>
computeIfAbsent
in interface Map<K,V>
default void forEach(@Nonnull BiConsumer<? super K,? super V> action)
If the supplied action
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in multiple round-trips between hazelcast nodes, as all map entries
will need to be pulled into the local node
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent
to the servers which own the partitions/keys. This results in a much less number of remote calls.
Note that in this case, side effects of the action
may not be visible to the local JVM.
If users intend to install the changed value in the map entry, the executeOnEntries(EntryProcessor)
method can be used instead
When this method is invoked using a hazelcast-client instance, the action
is always executed locally
V compute(@Nonnull K key, @Nonnull BiFunction<? super K,? super V,? extends V> remappingFunction)
If the supplied remappingFunction
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in multiple round-trips between hazelcast nodes, and possibly a livelock.
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent to the server which owns the key. This results in a single remote call. Also, the function would have exclusive access to the map entry during its execution. Note that in this case, the function class must be deployed on all the servers (either physically or via user-code-deployment).
When this method is invoked using a hazelcast-client instance, the remappingFunction
is always executed locally
V merge(@Nonnull K key, @Nonnull V value, @Nonnull BiFunction<? super V,? super V,? extends V> remappingFunction)
If the supplied remappingFunction
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in multiple round-trips between hazelcast nodes, and possibly a livelock.
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent to the server which owns the key. This results in a single remote call. Also, the function would have exclusive access to the map entry during its execution. Note that in this case, the function class must be deployed on all the servers (either physically or via user-code-deployment).
When this method is invoked using a hazelcast-client instance, the remappingFunction
is always executed locally
default void replaceAll(@Nonnull BiFunction<? super K,? super V,? extends V> function)
If the supplied function
is a lambda, anonymous class or an inner class,
it would be executed locally. Same would happen if it is not serializable.
This may result in multiple round-trips between hazelcast nodes, and possibly a livelock.
Otherwise (i.e. if it is a top-level class or a member class, and it is serializable), the function may be sent to the server which owns the key. This results in a single remote call. Also, the function would have exclusive access to the map entry during its execution. Note that in this case, the function class must be deployed on all the servers (either physically or via user-code-deployment).
When this method is invoked using a hazelcast-client instance, the function
is always executed locally
replaceAll
in interface ConcurrentMap<K,V>
replaceAll
in interface Map<K,V>
@Nonnull Iterator<Map.Entry<K,V>> iterator()
@Nonnull Iterator<Map.Entry<K,V>> iterator(int fetchSize)
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.Copyright © 2023 Hazelcast, Inc.. All rights reserved.