Package com.hazelcast.map

Interface IMap<K,V>

Type Parameters:

K - key type

V - value type

All Superinterfaces:

BaseMap<K,V>, ConcurrentMap<K,V>, DistributedObject, Iterable<Map.Entry<K,V>>, Map<K,V>

public interface IMap<K,V>
extends ConcurrentMap<K,V>, BaseMap<K,V>, Iterable<Map.Entry<K,V>>

Concurrent, distributed, observable and queryable map.

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:

• Methods, including but not limited to 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.
• The 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).
• Methods, including but not limited to 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.
• Be careful while using default interface method implementations from 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.

• executeOnKey(Object, EntryProcessor)
• submitToKey(Object, EntryProcessor)

However, there are following methods that run the EntryProcessor 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)

This applies to both 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:

• The time-to-live (TTL) expiration policy limits the lifetime of the entry relative to the time of the last write access performed on the entry. The default TTL value for the map may be configured using the 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.
• The max-idle expiration policy limits the lifetime of the entry relative to the time of the last read or write access performed on the entry. The max-idle value for the map may be configured using the 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:

• If the entry is new, i.e. the entry was created, it receives the default TTL value configured for the map using the time-to-live-seconds configuration setting. If this setting is not provided for the map, the entry receives an infinite TTL value.
• If the entry already exists, i.e. the entry was updated, its TTL value remains unchanged and its lifetime is prolonged by this TTL value.

The methods to which this procedure applies: 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).

See Also:

• ConcurrentMap

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K extends Object,V extends Object>

Method Summary

Modifier and Type	Method	Description
UUID	addEntryListener(MapListener listener, 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.
UUID	addEntryListener(MapListener listener, 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.
CompletionStage<Boolean>	deleteAsync(K key)	Asynchronously removes the given key, returning an CompletionStage on which the caller can register further computation stages to be invoked upon delete operation completion or block waiting for the operation to complete using one of blocking ways to wait on CompletionStage.toCompletableFuture().
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.
Collection<V>	localValues()	Returns an immutable collection locally owned values contained in this map.
Collection<V>	localValues(Predicate<K,V> predicate)	Queries the map of locally owned keys based on the specified predicate and returns an immutable collection of the values of matching 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)	Async version of executeOnKeys(java.util.Set<K>, com.hazelcast.map.EntryProcessor<K, V, R>).
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.

Methods inherited from interface com.hazelcast.map.BaseMap

isEmpty, size

Methods inherited from interface java.util.concurrent.ConcurrentMap

getOrDefault

Methods inherited from interface com.hazelcast.core.DistributedObject

destroy, getDestroyContextForTenant, getName, getPartitionKey, getServiceName

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.util.Map

equals, hashCode, isEmpty, size

Method Details

putAll

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.

Specified by:

putAll in interface Map<K,V>

containsKey

boolean containsKey(@Nonnull
 Object key)

Returns 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.

Specified by:

containsKey in interface BaseMap<K,V>

Specified by:

containsKey in interface Map<K,V>

Parameters:

key - The specified key.

Returns:

true if this map contains an entry for the specified key.

Throws:

NullPointerException - if the specified key is null

containsValue

boolean containsValue(@Nonnull
 Object value)

Specified by:

containsValue in interface Map<K,V>

Throws:

NullPointerException - if the specified value is null

get

V get(@Nonnull
 Object key)

Returns the value for the specified key, or 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.

Specified by:

get in interface BaseMap<K,V>

Specified by:

get in interface Map<K,V>

Parameters:

key - The specified key.

Returns:

The value for the specified key.

Throws:

NullPointerException - if the specified key is null

put

V put(@Nonnull
 K key,
 @Nonnull
 V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified 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.

Specified by:

put in interface BaseMap<K,V>

Specified by:

put in interface Map<K,V>

Parameters:

key - The specified key.

value - The value to associate with the key.

Returns:

Previous value associated with key or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key or value is null

remove

V remove(@Nonnull
 Object key)

Removes the mapping for a key from this map if it is present.

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.

Specified by:

remove in interface BaseMap<K,V>

Specified by:

remove in interface Map<K,V>

Parameters:

key - Remove the mapping for this key.

Returns:

The previous value associated with key, or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key is null

See Also:

• delete(Object)

remove

boolean remove(@Nonnull
 Object key,
 @Nonnull
 Object value)

Removes the entry for a key only if currently mapped to a given value. This is equivalent to

   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.

Specified by:

remove in interface BaseMap<K,V>

Specified by:

remove in interface ConcurrentMap<K,V>

Specified by:

remove in interface Map<K,V>

Parameters:

key - The specified key.

value - Remove the key if it has this value.

Returns:

true if the value was removed.

Throws:

NullPointerException - if the specified key or value is null

removeAll

void removeAll(@Nonnull
 Predicate<K,V> predicate)

Removes all entries which match with the supplied 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.

Parameters:

predicate - matching entries with this predicate will be removed from this map

Throws:

NullPointerException - if the specified predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

delete

void delete(@Nonnull
 Object key)

Removes the mapping for the key from this map if it is present.

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.

Specified by:

delete in interface BaseMap<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Throws:

ClassCastException - if the key is of an inappropriate type for this map (optional)

NullPointerException - if the specified key is null

See Also:

• remove(Object)

flush

void flush()

If this map has a MapStore, this method flushes all the local dirty entries.

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.

getAll

Map<K,V> getAll(@Nullable
 Set<K> keys)

Returns an immutable map of entries for the given 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.

Parameters:

keys - keys to get (keys inside the collection cannot be null)

Returns:

an immutable map of entries

Throws:

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.

loadAll

void loadAll(boolean replaceExistingValues)

Loads all keys into the store. This is a batch load operation so that an implementation can optimize multiple loads.

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.

Parameters:

replaceExistingValues - when true, existing values in the Map will be replaced by those loaded from the MapLoader

Since:

3.3

loadAll

void loadAll(@Nonnull
 Set<K> keys,
 boolean replaceExistingValues)

Loads the given keys. This is a batch load operation so that an implementation can optimize multiple loads.

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.

Parameters:

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 MapLoader

Since:

3.3

clear

void clear()

Clears the map and deletes the items from the backing map store.

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.

Specified by:

clear in interface Map<K,V>

See Also:

• evictAll()

getAsync

CompletionStage<V> getAsync(@Nonnull
 K key)

Asynchronously gets the given 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.

Parameters:

key - the key of the map entry

Returns:

CompletionStage from which the value of the key can be retrieved

Throws:

NullPointerException - if the specified key is null

See Also:

• CompletionStage

putAsync

CompletionStage<V> putAsync(@Nonnull
 K key,
 @Nonnull
 V value)

Asynchronously puts the given key and 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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

Returns:

CompletionStage from which the old value of the key can be retrieved

Throws:

NullPointerException - if the specified key or value is null

See Also:

• CompletionStage
• setAsync(Object, Object)

putAsync

CompletionStage<V> putAsync(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit)

Asynchronously puts the given key and value into this map with a given TTL (time to live) value.

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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Returns:

CompletionStage from which the old value of the key can be retrieved

Throws:

NullPointerException - if the specified key or value is null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

See Also:

• CompletionStage
• setAsync(Object, Object, long, TimeUnit)

putAsync

CompletionStage<V> putAsync(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 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.

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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Returns:

CompletionStage from which the old value of the key can be retrieved

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

See Also:

• CompletionStage
• setAsync(Object, Object, long, TimeUnit)

putAllAsync

CompletionStage<Void> putAllAsync(@Nonnull
 Map<? extends K,? extends V> map)

Asynchronously copies all of the mappings from the specified map to this map. This version doesn't support batching.

     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.

Parameters:

map - mappings to be stored in this map

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon putAll operation completion

Since:

4.1

See Also:

• CompletionStage

setAsync

CompletionStage<Void> setAsync(@Nonnull
 K key,
 @Nonnull
 V value)

Asynchronously puts the given key and value. The entry lives forever. Similar to the put operation except that set doesn't return the old value, which is more efficient.

   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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon set operation completion

Throws:

NullPointerException - if the specified key or value is null

See Also:

• CompletionStage

setAsync

CompletionStage<Void> setAsync(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 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()).

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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon set operation completion

Throws:

NullPointerException - if the specified key, value, ttlUnit

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

See Also:

• CompletionStage

setAsync

CompletionStage<Void> setAsync(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 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()).

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.

Parameters:

key - the key of the map entry

value - the new value of the map entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon set operation completion

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

See Also:

• CompletionStage

removeAsync

CompletionStage<V> removeAsync(@Nonnull
 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().

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.

Parameters:

key - The key of the map entry to remove

Returns:

CompletionStage from which the value removed from the map can be retrieved

Throws:

NullPointerException - if the specified key is null

See Also:

• CompletionStage

deleteAsync

CompletionStage<Boolean> deleteAsync(@Nonnull
 K key)

Asynchronously removes the given key, returning an CompletionStage on which the caller can register further computation stages to be invoked upon delete operation completion or block waiting for the operation to complete using one of blocking ways to wait on CompletionStage.toCompletableFuture().

Unlike removeAsync(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 removeAsync operation for better performance.

The returned CompletionStage completes with a boolean value: true if the key is in memory and deletion is successful, false otherwise.

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 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.

Parameters:

key - The key of the map entry to remove

Returns:

CompletionStage which completes with a boolean value, indicating the result of the deletion

Throws:

NullPointerException - if the specified key is null

See Also:

• CompletionStage

tryRemove

boolean tryRemove(@Nonnull
 K key,
 long timeout,
 @Nonnull
 TimeUnit timeunit)

Tries to remove the entry with the given key from this map within the specified timeout value. If the key is already locked by another thread and/or member, then this operation will wait the timeout amount for acquiring the lock.

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.

Parameters:

key - key of the entry

timeout - maximum time to wait for acquiring the lock for the key

timeunit - time unit for the timeout

Returns:

true if the remove is successful, false otherwise

Throws:

NullPointerException - if the specified key is null

tryPut

boolean tryPut(@Nonnull
 K key,
 @Nonnull
 V value,
 long timeout,
 @Nonnull
 TimeUnit timeunit)

Tries to put the given key and value into this map within a specified timeout value. If this method returns false, it means that the caller thread could not acquire the lock for the key within the timeout duration, thus the put operation is not successful.

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.

Parameters:

key - key of the entry

value - value of the entry

timeout - maximum time to wait

timeunit - time unit for the timeout

Returns:

true if the put is successful, false otherwise

Throws:

NullPointerException - if the specified key or value is null

put

V put(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit)

Puts an entry into this map with a given TTL (time to live) value.

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.

Specified by:

put in interface BaseMap<K,V>

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key or value is null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

put

V put(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 TimeUnit maxIdleUnit)

Puts an entry into this map with a given TTL (time to live) value and max idle time value.

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

putTransient

void putTransient(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 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.

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Throws:

NullPointerException - if the specified key or value is null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

putTransient

void putTransient(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 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.

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

putIfAbsent

V putIfAbsent(@Nonnull
 K key,
 @Nonnull
 V value)

If the specified key is not already associated with a value, associate it with the given value. This is equivalent to

   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.

Specified by:

putIfAbsent in interface BaseMap<K,V>

Specified by:

putIfAbsent in interface ConcurrentMap<K,V>

Specified by:

putIfAbsent in interface Map<K,V>

Parameters:

key - The specified key.

value - The value to associate with the key when there is no previous value.

Returns:

a clone of the previous value

Throws:

NullPointerException - if the specified key or value is null

putIfAbsent

V putIfAbsent(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 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.

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key or value is null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

putIfAbsent

V putIfAbsent(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 TimeUnit maxIdleUnit)

Puts an entry into this map with a given TTL (time to live) value and max idle time value. if the specified key is not already associated with a value.

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Returns:

old value of the entry

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

replace

boolean replace(@Nonnull
 K key,
 @Nonnull
 V oldValue,
 @Nonnull
 V newValue)

Replaces the entry for a key only if currently mapped to a given value. This is equivalent to

   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.

Specified by:

replace in interface BaseMap<K,V>

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

Parameters:

key - The specified key.

oldValue - Replace the key value if it is the old value.

newValue - The new value to replace the old value.

Returns:

true if the value was replaced.

Throws:

NullPointerException - if any of the specified parameters are null

replace

V replace(@Nonnull
 K key,
 @Nonnull
 V value)

Replaces the entry for a key only if it is currently mapped to some value. This is equivalent to

   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.

Specified by:

replace in interface BaseMap<K,V>

Specified by:

replace in interface ConcurrentMap<K,V>

Specified by:

replace in interface Map<K,V>

Parameters:

key - The specified key.

value - The value to replace the previous value.

Returns:

The previous value associated with key, or null if there was no mapping for key.

Throws:

NullPointerException - if the specified key or value is null

set

void set(@Nonnull
 K key,
 @Nonnull
 V value)

Puts an entry into this map without returning the old value (which is more efficient than 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.

Specified by:

set in interface BaseMap<K,V>

Parameters:

key - key of the entry

value - value of the entry

Throws:

NullPointerException - if the specified key or value is null

set

void set(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 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()).

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

Throws:

NullPointerException - if the specified key or value is null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

set

void set(@Nonnull
 K key,
 @Nonnull
 V value,
 long ttl,
 @Nonnull
 TimeUnit ttlUnit,
 long maxIdle,
 @Nonnull
 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()).

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.

Parameters:

key - key of the entry

value - value of the entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

ttlUnit - time unit for the TTL

maxIdle - 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-Idle

Throws:

NullPointerException - if the specified key, value, ttlUnit or maxIdleUnit are null

UnsupportedOperationException - if the underlying map storage doesn't support TTL-based expiration (all in-memory storages support it).

setAll

void setAll(@Nonnull
 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()).

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.

Since:

4.1

setAllAsync

CompletionStage<Void> setAllAsync(@Nonnull
 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. This version doesn't support batching.

     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.

Parameters:

map - mappings to be stored in this map

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon setAll operation completion

Since:

4.1

See Also:

• CompletionStage

lock

void lock(@Nonnull
 K key)

Acquires the lock for the specified 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.

Parameters:

key - key to lock

Throws:

NullPointerException - if the specified key is null

lock

void lock(@Nonnull
 K key,
 long leaseTime,
 @Nullable
 TimeUnit timeUnit)

Acquires the lock for the specified key for the specified lease time.

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.

Parameters:

key - the key to lock

leaseTime - time to wait before releasing the lock

timeUnit - unit of time to specify lease time

Throws:

NullPointerException - if the specified key is null

IllegalArgumentException - if the leaseTime is not positive

isLocked

boolean isLocked(@Nonnull
 K key)

Checks the lock for the specified 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.

Parameters:

key - the key that is checked for lock

Returns:

true if lock is acquired, false otherwise

Throws:

NullPointerException - if the specified key is null

tryLock

boolean tryLock(@Nonnull
 K key)

Tries to acquire the lock for the specified 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.

Parameters:

key - the key to lock

Returns:

true if lock is acquired, false otherwise

Throws:

NullPointerException - if the specified key is null

tryLock

boolean tryLock(@Nonnull
 K key,
 long time,
 @Nullable
 TimeUnit timeunit)
         throws InterruptedException

Tries to acquire the lock for the specified key.

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:

• the lock is acquired by the current thread, or
• the specified waiting time elapses.

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.

Parameters:

key - key to lock in this map

time - maximum time to wait for the lock

timeunit - time unit of the time argument

Returns:

true if the lock was acquired, false if the waiting time elapsed before the lock was acquired

Throws:

NullPointerException - if the specified key is null

InterruptedException - if interrupted while trying to acquire the lock

tryLock

boolean tryLock(@Nonnull
 K key,
 long time,
 @Nullable
 TimeUnit timeunit,
 long leaseTime,
 @Nullable
 TimeUnit leaseTimeunit)
         throws InterruptedException

Tries to acquire the lock for the specified key for the specified lease time.

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:

• the lock is acquired by the current thread, or
• the specified waiting time elapses.

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.

Parameters:

key - key to lock in this map

time - maximum time to wait for the lock

timeunit - time unit of the time argument

leaseTime - time to wait before releasing the lock

leaseTimeunit - unit of time to specify lease time

Returns:

true if the lock was acquired, false if the waiting time elapsed before the lock was acquired

Throws:

NullPointerException - if the specified key is null

InterruptedException - if interrupted while trying to acquire the lock

unlock

void unlock(@Nonnull
 K key)

Releases the lock for the specified key. It never blocks and returns immediately.

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.

Parameters:

key - the key to unlock

Throws:

NullPointerException - if the specified key is null

IllegalMonitorStateException - if the current thread does not hold this lock

forceUnlock

void forceUnlock(@Nonnull
 K key)

Releases the lock for the specified key regardless of the lock owner. It always successfully unlocks the key, never blocks, and returns 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.

Parameters:

key - the key to unlock

Throws:

NullPointerException - if the specified key is null

addLocalEntryListener

UUID addLocalEntryListener(@Nonnull
 MapListener listener)

Adds a 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.

Parameters:

listener - MapListener for this map

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

UnsupportedOperationException - if this operation is not supported, for example on a Hazelcast client

NullPointerException - if the listener is null

See Also:

• localKeySet()
• MapListener

addLocalEntryListener

UUID addLocalEntryListener(@Nonnull
 MapListener listener,
 @Nonnull
 Predicate<K,V> predicate,
 boolean includeValue)

Adds a 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.

Parameters:

listener - MapListener for this map

predicate - predicate for filtering entries

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

UnsupportedOperationException - if this operation isn't supported, for example on a Hazelcast client

NullPointerException - if the listener or predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

See Also:

• MapListener

addLocalEntryListener

UUID addLocalEntryListener(@Nonnull
 MapListener listener,
 @Nonnull
 Predicate<K,V> predicate,
 @Nullable
 K key,
 boolean includeValue)

Adds a local entry listener for this map.

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.

Parameters:

listener - MapListener for this map

predicate - predicate for filtering entries

key - key to listen for

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

NullPointerException - if the listener is null

NullPointerException - if the predicate is null

UnsupportedOperationException - if this operation isn't supported, for example on a Hazelcast client

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

See Also:

• MapListener

addInterceptor

String addInterceptor(@Nonnull
 MapInterceptor interceptor)

Adds an interceptor for this map.

Added interceptor will intercept operations and execute user defined methods. They will cancel operations if the user defined method throws an exception.

Parameters:

interceptor - map interceptor

Returns:

ID of registered interceptor

removeInterceptor

boolean removeInterceptor(@Nonnull
 String id)

Removes the given interceptor for this map, so it will not intercept operations anymore.

Parameters:

id - registration ID of the map interceptor

Returns:

true if registration is removed, false otherwise

addEntryListener

UUID addEntryListener(@Nonnull
 MapListener listener,
 boolean includeValue)

Adds a MapListener for this map.

To receive an event, you should implement a corresponding MapListener sub-interface for that event.

Parameters:

listener - MapListener for this map

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

NullPointerException - if the specified listener is null

See Also:

• MapListener

removeEntryListener

boolean removeEntryListener(@Nonnull
 UUID id)

Removes the specified entry listener.

Returns silently if there is no such listener added before.

Parameters:

id - ID of registered listener

Returns:

true if registration is removed, false otherwise

addPartitionLostListener

UUID addPartitionLostListener(@Nonnull
 MapPartitionLostListener listener)

Adds a MapPartitionLostListener.

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.

Parameters:

listener - the added MapPartitionLostListener

Returns:

returns the registration ID for the MapPartitionLostListener

Throws:

NullPointerException - if listener is null

See Also:

• removePartitionLostListener(UUID)
• PartitionLostListener

removePartitionLostListener

boolean removePartitionLostListener(@Nonnull
 UUID id)

Removes the specified map partition lost listener.

Returns silently if there is no such listener was added before.

Parameters:

id - ID of registered listener

Returns:

true if registration is removed, false otherwise

Throws:

NullPointerException - if id is null

addEntryListener

UUID addEntryListener(@Nonnull
 MapListener listener,
 @Nonnull
 K key,
 boolean includeValue)

Adds a 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.

Parameters:

listener - MapListener for this map

key - key to listen for

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

NullPointerException - if the specified listener is null

NullPointerException - if the specified key is null

See Also:

• MapListener

addEntryListener

UUID addEntryListener(@Nonnull
 MapListener listener,
 @Nonnull
 Predicate<K,V> predicate,
 boolean includeValue)

Adds a MapListener for this map.

To receive an event, you should implement a corresponding MapListener sub-interface for that event.

Parameters:

listener - the added continuous MapListener for this map

predicate - predicate for filtering entries

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

NullPointerException - if the specified listener or predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

See Also:

• MapListener

addEntryListener

UUID addEntryListener(@Nonnull
 MapListener listener,
 @Nonnull
 Predicate<K,V> predicate,
 @Nullable
 K key,
 boolean includeValue)

Adds a MapListener for this map.

To receive an event, you should implement a corresponding MapListener sub-interface for that event.

Parameters:

listener - the continuous MapListener for this map

predicate - predicate for filtering entries

key - key to listen for

includeValue - true if EntryEvent should contain the value

Returns:

a UUID.randomUUID().toString() which is used as a key to remove the listener

Throws:

NullPointerException - if the specified listener or predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

See Also:

• MapListener

getEntryView

EntryView<K,V> getEntryView(@Nonnull
 K key)

Returns the EntryView for the specified key.

Not to misuse this method, please know these points:

This method cannot be used as a replacement for get(java.lang.Object).

This method only looks up entries already in memory and does not load missing ones from MapStore.

Calling this method does not update entry or map level statistics.

Calling this method is not counted as an access, so it doesn't have any effect on eviction and expiration.

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.

Parameters:

key - the key of the entry

Returns:

EntryView of the specified key

Throws:

NullPointerException - if the specified key is null

See Also:

• EntryView

evict

boolean evict(@Nonnull
 K key)

Evicts the specified key from this map.

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.

Parameters:

key - the specified key to evict from this map

Returns:

true if the key is evicted, false otherwise

Throws:

NullPointerException - if the specified key is null

See Also:

• delete(Object)
• remove(Object)

evictAll

void evictAll()

Evicts all keys from this map except the locked ones.

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) .

Since:

3.3

See Also:

• clear()

keySet

@Nonnull
Set<K> keySet()

Returns an immutable set clone of the keys 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.

Specified by:

keySet in interface BaseMap<K,V>

Specified by:

keySet in interface Map<K,V>

Returns:

an immutable set clone of the keys contained in this map

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

values

@Nonnull
Collection<V> values()

Returns an immutable collection clone of the values contained in this map.

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.

Specified by:

values in interface BaseMap<K,V>

Specified by:

values in interface Map<K,V>

Returns:

an immutable collection clone of the values contained in this map

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

entrySet

@Nonnull
Set<Map.Entry<K,V>> entrySet()

Returns an immutable 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.

Specified by:

entrySet in interface Map<K,V>

Returns:

an immutable set clone of the keys mappings in this map

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

keySet

Set<K> keySet(@Nonnull
 Predicate<K,V> predicate)

Queries the map based on the specified predicate and returns an immutable 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.

Specified by:

keySet in interface BaseMap<K,V>

Parameters:

predicate - specified query criteria

Returns:

result key set of the query

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

NullPointerException - if the predicate is null

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

entrySet

Set<Map.Entry<K,V>> entrySet(@Nonnull
 Predicate<K,V> predicate)

Queries the map based on the specified predicate and returns an immutable set of the 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.

Parameters:

predicate - specified query criteria

Returns:

result entry set of the query

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

NullPointerException - if the predicate is null

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

values

Collection<V> values(@Nonnull
 Predicate<K,V> predicate)

Queries the map based on the specified predicate and returns an immutable collection of the values of matching entries.

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.

Specified by:

values in interface BaseMap<K,V>

Parameters:

predicate - specified query criteria

Returns:

result value collection of the query

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

NullPointerException - if the predicate is null

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

localValues

Collection<V> localValues()

Returns an immutable collection locally owned values contained in this map.

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.

Returns:

an immutable collection clone of the values contained in this map

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

Since:

5.4.0

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

localValues

Collection<V> localValues(@Nonnull
 Predicate<K,V> predicate)

Queries the map of locally owned keys based on the specified predicate and returns an immutable collection of the values of matching entries.

Specified predicate runs on local member.

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.

Parameters:

predicate - specified query criteria

Returns:

result value collection of the query

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

NullPointerException - if the predicate is null

Since:

5.4.0

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

localKeySet

Set<K> localKeySet()

Returns the locally owned immutable set of keys.

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.

Returns:

locally owned immutable set of keys

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

localKeySet

Set<K> localKeySet(@Nonnull
 Predicate<K,V> predicate)

Returns an immutable set of the keys of matching locally owned entries.

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.

Parameters:

predicate - specified query criteria

Returns:

an immutable set of the keys of matching locally owned entries

Throws:

QueryResultSizeExceededException - if query result size limit is exceeded

UnsupportedOperationException - if this operation isn't supported, for example on a Hazelcast client

See Also:

• ClusterProperty.QUERY_RESULT_SIZE_LIMIT

addIndex

default void addIndex(IndexType type,
 String... attributes)

Convenient method to add an index to this map with the given type and attributes. Attributes are indexed in ascending order.

Parameters:

type - Index type.

attributes - Attributes to be indexed.

See Also:

• addIndex(IndexConfig)

addIndex

void addIndex(IndexConfig indexConfig)

Adds an index to this map for the specified entries so that queries can run faster.

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 predicates
 

Index 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.

Parameters:

indexConfig - Index configuration.

getLocalMapStats

LocalMapStats getLocalMapStats()

Returns LocalMapStats for this map.

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.

Returns:

this map's local statistics

executeOnKey

<R> R executeOnKey(@Nonnull
 K key,
 @Nonnull
 EntryProcessor<K,V,R> entryProcessor)

Applies the user defined 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:

1. partition-thread (fetch & lock)
2. execution-thread (process)
3. partition-thread (set & unlock, or just unlock if no changes)

If the EntryProcessor implements the Offloadable and ReadOnly interfaces, the processing will be offloaded to the given ExecutorService allowing unblocking the partition-thread. Since the EntryProcessor is not supposed to do any changes to the Entry, the key will NOT be locked for the time-span of the processing. In this case the threading looks as follows:

1. partition-thread (fetch)
2. execution-thread (process)

In this case, the EntryProcessor.getBackupProcessor() has to return null; otherwise an IllegalArgumentException exception is thrown.

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.

Type Parameters:

R - the entry processor return type

Returns:

result of EntryProcessor.process(Map.Entry)

Throws:

NullPointerException - if the specified key is null

See Also:

• Offloadable
• ReadOnly

executeOnKeys

<R> Map<K,R> executeOnKeys(@Nonnull
 Set<K> keys,
 @Nonnull
 EntryProcessor<K,V,R> entryProcessor)

Applies the user defined 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;
         });
 

Type Parameters:

R - the entry processor return type

Parameters:

keys - The keys to execute the entry processor on. Can be empty, in that case it's a local no-op

Returns:

results of EntryProcessor.process(Map.Entry)

Throws:

NullPointerException - if there's null element in keys

submitToKeys

<R> CompletionStage<Map<K,R>> submitToKeys(@Nonnull
 Set<K> keys,
 @Nonnull
 EntryProcessor<K,V,R> entryProcessor)

Async version of executeOnKeys(java.util.Set<K>, com.hazelcast.map.EntryProcessor<K, V, R>).

Type Parameters:

R - return type for entry processor

Parameters:

keys - the keys to execute the entry processor on. Can be empty, in that case it's a local no-op

entryProcessor - the processor to process the keys

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon set operation completion

See Also:

• CompletionStage

submitToKey

<R> CompletionStage<R> submitToKey(@Nonnull
 K key,
 @Nonnull
 EntryProcessor<K,V,R> entryProcessor)

Applies the user defined 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:

1. partition-thread (fetch & lock)
2. execution-thread (process)
3. partition-thread (set & unlock, or just unlock if no changes)

If the EntryProcessor implements the Offloadable and ReadOnly interfaces the processing will be offloaded to the given ExecutorService allowing unblocking the partition-thread. Since the EntryProcessor is not supposed to do any changes to the Entry the key will NOT be locked for the time-span of the processing. In this case the threading looks as follows:

1. partition-thread (fetch & lock)
2. execution-thread (process)

In this case the EntryProcessor.getBackupProcessor() has to return null; otherwise an IllegalArgumentException exception is thrown.

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.

Type Parameters:

R - return type for entry processor

Parameters:

key - key to be processed

entryProcessor - processor to process the key

Returns:

CompletionStage on which client code can block waiting for the operation to complete or register callbacks to be invoked upon set operation completion

See Also:

• Offloadable
• ReadOnly
• CompletionStage

executeOnEntries

<R> Map<K,R> executeOnEntries(@Nonnull
 EntryProcessor<K,V,R> entryProcessor)

Applies the user defined 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.

Type Parameters:

R - return type for entry processor

Parameters:

entryProcessor - processor to process the keys

Returns:

results mapped by entry key

executeOnEntries

<R> Map<K,R> executeOnEntries(@Nonnull
 EntryProcessor<K,V,R> entryProcessor,
 @Nonnull
 Predicate<K,V> predicate)

Applies the user defined 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.

Type Parameters:

R - return type for entry processor

Parameters:

entryProcessor - processor to process the keys

predicate - predicate to filter the entries with

Returns:

results mapped by entry key

Throws:

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

aggregate

<R> R aggregate(@Nonnull
 Aggregator<? super Map.Entry<K,V>,R> aggregator)

Applies the aggregation logic on all map entries and returns the result

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.

Type Parameters:

R - type of the result

Parameters:

aggregator - aggregator to aggregate the entries with

Returns:

the result of the given type

Since:

3.8

aggregate

<R> R aggregate(@Nonnull
 Aggregator<? super Map.Entry<K,V>,R> aggregator,
 @Nonnull
 Predicate<K,V> predicate)

Applies the aggregation logic on map entries filtered with the Predicated and returns the result

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.

Type Parameters:

R - type of the result

Parameters:

aggregator - aggregator to aggregate the entries with

predicate - predicate to filter the entries with

Returns:

the result of the given type

Throws:

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

Since:

3.8

project

<R> Collection<R> project(@Nonnull
 Projection<? super Map.Entry<K,V>,R> projection)

Applies the projection logic on all map entries and returns the result

Type Parameters:

R - type of the result

Parameters:

projection - projection to transform the entries with (may return null)

Returns:

the result of the given type

Since:

3.8

project

<R> Collection<R> project(@Nonnull
 Projection<? super Map.Entry<K,V>,R> projection,
 @Nonnull
 Predicate<K,V> predicate)

Applies the projection logic on map entries filtered with the Predicated and returns the result

Type Parameters:

R - type of the result

Parameters:

projection - projection to transform the entries with (may return null)

predicate - predicate to filter the entries with

Returns:

the result of the given type

Throws:

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

Since:

3.8

getQueryCache

QueryCache<K,V> getQueryCache(@Nonnull
 String name)

Returns corresponding 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.

Parameters:

name - the name of QueryCache

Returns:

the QueryCache instance or null if there is no corresponding QueryCacheConfig

Throws:

NullPointerException - if the specified name is null

Since:

3.8

See Also:

• QueryCache

getQueryCache

QueryCache<K,V> getQueryCache(@Nonnull
 String name,
 @Nonnull
 Predicate<K,V> predicate,
 boolean includeValue)

Creates an always up to date snapshot of this 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.

Parameters:

name - the name of QueryCache

predicate - the predicate for filtering entries

includeValue - true if this QueryCache is allowed to cache values of entries, otherwise false

Returns:

the QueryCache instance with the supplied name

Throws:

NullPointerException - if the specified name or predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

Since:

3.8

See Also:

• QueryCache

getQueryCache

QueryCache<K,V> getQueryCache(@Nonnull
 String name,
 @Nonnull
 MapListener listener,
 @Nonnull
 Predicate<K,V> predicate,
 boolean includeValue)

Creates an always up to date snapshot of this 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.

Parameters:

name - the name of QueryCache

listener - the MapListener which will be used to listen this QueryCache

predicate - the predicate for filtering entries

includeValue - true if this QueryCache is allowed to cache values of entries, otherwise false

Returns:

the QueryCache instance with the supplied name

Throws:

NullPointerException - if the specified name or listener or predicate is null

IllegalArgumentException - if the predicate is a PagingPredicate or is a PartitionPredicate that includes a PagingPredicate

Since:

3.8

See Also:

• QueryCache

setTtl

boolean setTtl(@Nonnull
 K key,
 long ttl,
 @Nonnull
 TimeUnit timeunit)

Updates the TTL (time to live) value of the entry specified by 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.

Parameters:

key - the key of the map entry

ttl - maximum time for this entry to stay in the map (0 means infinite, negative means map config default)

timeunit - time unit for the TTL

Returns:

true if the entry exists and its ttl value is changed, false otherwise

Throws:

NullPointerException - if the specified key or timeunit is null.

Since:

3.11

computeIfPresent

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

Specified by:

computeIfPresent in interface ConcurrentMap<K,V>

Specified by:

computeIfPresent in interface Map<K,V>

Since:

4.1

computeIfAbsent

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

Specified by:

computeIfAbsent in interface ConcurrentMap<K,V>

Specified by:

computeIfAbsent in interface Map<K,V>

Since:

4.1

forEach

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

Specified by:

forEach in interface ConcurrentMap<K,V>

Specified by:

forEach in interface Map<K,V>

compute

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

Specified by:

compute in interface ConcurrentMap<K,V>

Specified by:

compute in interface Map<K,V>

Since:

4.1

merge

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

Specified by:

merge in interface ConcurrentMap<K,V>

Specified by:

merge in interface Map<K,V>

Since:

4.1

replaceAll

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

Specified by:

replaceAll in interface ConcurrentMap<K,V>

Specified by:

replaceAll in interface Map<K,V>

Since:

4.1

iterator

@Nonnull
Iterator<Map.Entry<K,V>> iterator()

Returns an iterator over the entries of the map. It sequentially iterates partitions. It starts to iterate on partition 0 and it finishes the iteration with the last partition (n = 271 by default). The keys are fetched in batches for the constant heap utilization.

Specified by:

iterator in interface Iterable<K>

Returns:

an iterator for the map entries

Since:

4.2

iterator

@Nonnull
Iterator<Map.Entry<K,V>> iterator(int fetchSize)

Returns an iterator over the entries of the map. It sequentially iterates partitions. It starts to iterate on partition 0 and it finishes the iteration with the last partition (n = 271 by default). The keys are fetched in batches for the constant heap utilization.

Parameters:

fetchSize - size for fetching keys in bulk. This size can be thought of as page size for iteration. But notice that at every fetch only keys are retrieved, not values. Values are retrieved on each iterate.

Returns:

an iterator for the map entries

Since:

4.2