com.hazelcast.map.IMap Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2024, Hazelcast, Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.hazelcast.map;
import com.hazelcast.aggregation.Aggregator;
import com.hazelcast.config.IndexConfig;
import com.hazelcast.config.IndexType;
import com.hazelcast.core.EntryView;
import com.hazelcast.map.listener.MapListener;
import com.hazelcast.map.listener.MapPartitionLostListener;
import com.hazelcast.projection.Projection;
import com.hazelcast.query.Predicate;
import com.hazelcast.query.impl.IndexUtils;
import com.hazelcast.spi.properties.ClusterProperty;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Collection;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.TimeUnit;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Function;
/**
* Concurrent, distributed, observable and queryable map.
*
* This class is not a general-purpose {@code ConcurrentMap}
* implementation! While this class implements the {@code Map} interface,
* it intentionally violates {@code Map's} general contract, which mandates
* the use of the {@code equals} method when comparing objects. Instead of
* the {@code 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 {@code get}, {@code containsKey},
* {@code containsValue}, {@code evict}, {@code remove}, {@code put},
* {@code putIfAbsent}, {@code replace}, {@code lock}, {@code unlock}, do
* not use {@code hashCode} and {@code equals} implementations of keys.
* Instead, they use {@code hashCode} and {@code equals} of binary (serialized)
* forms of the objects.
* - The {@code 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 {@link IMap#get(Object)}.
* - Methods, including but not limited to {@code keySet}, {@code values},
* {@code 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
* {@link ConcurrentMap} and {@link 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 {@code 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.
*
* - {@link IMap#executeOnKey(Object, EntryProcessor)}
* - {@link IMap#submitToKey(Object, EntryProcessor)}
*
* However, there are following methods that run the {@code EntryProcessor}
* on more than one entry.
* These operations are not lock-aware.
* The {@code EntryProcessor} will process the entries no matter if they
* are locked or not.
*
* - {@link IMap#executeOnEntries(EntryProcessor)}
* - {@link IMap#executeOnEntries(EntryProcessor, Predicate)}
* - {@link IMap#executeOnKeys(Set, EntryProcessor)}
*
* This applies to both {@code EntryProcessor} and {@code BackupEntryProcessor}.
*
* 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 {@code 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
* {@link #put(Object, Object, long, TimeUnit) 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 {@code 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 server-side
* {@code max-size} setting
* and the eviction policy may be configured using the
* {@code 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 {@link 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 {@code 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: {@link #put(Object, Object) put},
* {@link #set(Object, Object) set}, {@link #putAsync(Object, Object) putAsync},
* {@link #setAsync(Object, Object) setAsync},
* {@link #tryPut(Object, Object, long, TimeUnit) tryPut},
* {@link #putAll(Map) putAll}, {@link #setAll(Map) setAll},
* {@link #putAllAsync(Map) putAllAsync}, {@link #setAllAsync(Map) setAllAsync},
* {@link #replace(Object, Object, Object)} and {@link #replace(Object, Object)}.
*
*
* Asynchronous methods
*
* Asynchronous methods return a {@link CompletionStage} that can be used to
* chain further computation stages. Alternatively, a {@link java.util.concurrent.CompletableFuture}
* can be obtained via {@link 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 {@link java.util.concurrent.Executor} argument are performed
* by the {@link java.util.concurrent.ForkJoinPool#commonPool()} (unless it does not
* support a parallelism level of at least 2, in which case a new {@code Thread} is
* created per task).
*
* @param key type
* @param value type
* @see java.util.concurrent.ConcurrentMap
*/
@SuppressWarnings("MethodCount")
public interface IMap extends ConcurrentMap, BaseMap , Iterable> {
/**
* {@inheritDoc}
*
* 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
Note:
* Use {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @throws NullPointerException if the specified key or value is null
*/
V put(@Nonnull K key, @Nonnull V value);
/**
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @return old value of the entry
* @throws NullPointerException if the specified key or value is {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
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 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @return old value of the entry
* @throws NullPointerException if the specified key, value, ttlUnit or maxIdleUnit are {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
V put(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* {@inheritDoc}
*
* Note:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @return a clone of the previous value
* @throws NullPointerException if the specified {@code key} or {@code value}
* is {@code null}
*/
V putIfAbsent(@Nonnull K key, @Nonnull V value);
/**
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @return old value of the entry
* @throws NullPointerException if the specified {@code key} or {@code value}
* is {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
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 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @return old value of the entry
* @throws NullPointerException if the specified {@code key}, {@code value}, {@code ttlUnit} or
* {@code maxIdleUnit} are {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
V putIfAbsent(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* Same as {@link #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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
* Warning 2:
*
* Time resolution for TTL is seconds. The given TTL value is rounded to
* next closest second value.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @throws NullPointerException if the specified key or value is {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
void putTransient(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit ttlUnit);
/**
* Same as {@link #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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
* Warning 2:
*
* Time resolution for TTL is seconds. The given TTL value is rounded to
* next closest second value.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @throws NullPointerException if the specified {@code key}, {@code value}, {@code ttlUnit} or
* {@code maxIdleUnit} are {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
void putTransient(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If no value is found with {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param timeout maximum time to wait
* @param timeunit time unit for the timeout
* @return {@code true} if the put is successful, {@code false} otherwise
* @throws NullPointerException if the specified key or value is {@code null}
*/
boolean tryPut(@Nonnull K key, @Nonnull V value,
long timeout, @Nonnull TimeUnit timeunit);
/**
* {@inheritDoc}
*
* 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
* an attempt will be made to load the value from
* the map store backing the map, which may come at a significant
* performance cost. Exceptions thrown by the map 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-through persistence mode is configured,
* an attempt will be made for each element to store it
* before the element is added in memory, which may come at a
* significant performance cost. Exceptions thrown by the map 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*/
void putAll(@Nonnull Map m);
/**
* {@inheritDoc}
*
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If value with {@code key} is not found in memory
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* @throws NullPointerException if the specified key is {@code null}
*/
V get(@Nonnull Object key);
/**
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code keys}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If any keys are not found in memory, an attempt will be made
* to load the missing keys. Exceptions thrown by
* the map store fail the operation and are propagated to the caller.
*
* @param keys keys to get (keys inside the collection cannot be null)
* @return an immutable map of entries
* @throws NullPointerException if any of the specified
* keys are null or if any key or any value returned
* during the loading of missing keys is {@code null}.
*/
Map getAll(@Nullable Set keys);
/**
* 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 {@link #delete} and avoid the cost of serialization and network
* transfer.
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is removed from the memory, an attempt will be made is
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @throws NullPointerException if the specified key is null
* @see #delete(Object)
*/
V remove(@Nonnull Object key);
/**
* {@inheritDoc}
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If no value is found with {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is removed from the memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @throws NullPointerException if the specified key or value is null
*/
boolean remove(@Nonnull Object key, @Nonnull Object value);
/**
* 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, an attempt will be made to
* remove the value from the map store. 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, {@link com.hazelcast.map.ReachedMaxSizeException} may be
* thrown if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param predicate matching entries with this predicate will be removed
* from this map
* @throws NullPointerException if the specified predicate is null
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
*/
void removeAll(@Nonnull Predicate predicate);
/**
* 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If write-through persistence mode is configured, before the value
* is removed from the memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param timeout maximum time to wait for acquiring the lock for the key
* @param timeunit time unit for the timeout
* @return {@code true} if the remove is successful, {@code false} otherwise
* @throws NullPointerException if the specified key is {@code null}
*/
boolean tryRemove(@Nonnull K key, long timeout, @Nonnull TimeUnit timeunit);
/**
* Removes the mapping for the key from this map if it is present.
*
* Unlike {@link #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 memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param 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)
* @throws NullPointerException if the specified key is null
* @see #remove(Object)
*/
void delete(@Nonnull Object key);
/**
* {@inheritDoc}
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@code key} is not found in memory,
* an attempt will be made 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @throws NullPointerException if the specified key or value is {@code null}
*/
V replace(@Nonnull K key, @Nonnull V value);
/**
* {@inheritDoc}
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
* Warning 2:
*
* This method may return {@code 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 {@code false}. Hazelcast doesn't guarantee exactly once invocation.
*
*
Interactions with the map store
*
* If value with {@code key} is not found in memory,
* an attempt will be made 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, an attempt will be made to
* write the value into the map store. 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, {@link com.hazelcast.map.ReachedMaxSizeException} may be
* thrown if the write-behind queue has reached its per-node maximum capacity.
*
* @throws NullPointerException if any of the specified parameters are {@code null}
*/
boolean replace(@Nonnull K key, @Nonnull V oldValue, @Nonnull V newValue);
/**
* {@inheritDoc}
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If {@code key} is not found in memory
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* @throws NullPointerException if the specified key is {@code null}
*/
boolean containsKey(@Nonnull Object key);
/**
* {@inheritDoc}
*
* @throws NullPointerException if the specified value is {@code null}
*/
boolean containsValue(@Nonnull Object value);
/**
* Clears the map and deletes the items from the backing map store.
*
* The MAP_CLEARED event is fired for any registered listeners.
* See {@link com.hazelcast.core.EntryListener#mapCleared(MapEvent)}.
*
* To clear the map without removing the items from the map store,
* use {@link #evictAll}.
*
*
Interactions with the map store
*
* On each partition deletes all the entries
* with the keys that the given partition stores. Exceptions thrown
* by the delete attempt are not propagated to the caller.
*
* @see #evictAll
*/
@Override
void clear();
/**
* 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 {@link QueryResultSizeExceededException}
* if {@link ClusterProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return an immutable set clone of the keys contained in this map
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see ClusterProperty#QUERY_RESULT_SIZE_LIMIT
*/
@Nonnull
Set keySet();
/**
* Queries the map based on the specified predicate and
* returns the keys of matching entries.
*
* @param predicate specified query criteria.
* @return result key set of the query.
* @throws NullPointerException if the specified predicate is null.
*/
Set keySet(Predicate predicate);
/**
* Queries the map based on the specified predicate and
* returns the values of matching entries.
*
* @param predicate specified query criteria.
* @return result value collection of the query.
* @throws NullPointerException if the predicate is null
*/
Collection values(Predicate predicate);
/**
* 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 {@link QueryResultSizeExceededException}
* if {@link ClusterProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return an immutable collection clone of the values contained in this map
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see ClusterProperty#QUERY_RESULT_SIZE_LIMIT
*/
@Nonnull
Collection values();
/**
* Returns an immutable {@link 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 {@link QueryResultSizeExceededException}
* if {@link ClusterProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return an immutable set clone of the keys mappings in this map
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see ClusterProperty#QUERY_RESULT_SIZE_LIMIT
*/
@Nonnull
Set> entrySet();
/**
* 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 {@link QueryResultSizeExceededException}
* if {@link ClusterProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @param predicate specified query criteria
* @return result entry set of the query
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @throws NullPointerException if the predicate is {@code null}
* @see ClusterProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set> entrySet(@Nonnull Predicate predicate);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code function} is always executed locally
*
*
* @since 4.1
*/
default void replaceAll(@Nonnull BiFunction function) {
ConcurrentMap.super.replaceAll(function);
}
/**
* Puts an entry into this map without returning the old value
* (which is more efficient than {@code 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @throws NullPointerException if the specified key or value is {@code null}
*/
void set(@Nonnull K key, @Nonnull V value);
/**
* Puts an entry into this map with a given TTL (time to live) value,
* without returning the old value (which is more efficient than {@code 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @throws NullPointerException if the specified key or value is {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
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 and
* max idle time value without returning the old value (which is more
* efficient than {@code 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 {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @throws NullPointerException if the specified key, value, ttlUnit or maxIdleUnit are {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
*/
void set(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* 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 {@code 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,
* an attempt will be made for each element to store it
* before the element is added in memory, which may come at a
* significant performance cost. Exceptions thrown by the map 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @since 4.1
*/
void setAll(@Nonnull Map map);
/**
* Applies the user defined {@code EntryProcessor} to the entry mapped by the {@code key}.
* Returns the object which is the result of the {@link EntryProcessor#process(Map.Entry)} method.
*
* See {@link #submitToKey(Object, EntryProcessor)} for an async version of this method.
*
*
Interactions with the map store
*
* If value with {@code key} is not found in memory,
* an attempt will be made 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, an attempt will be made 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param the entry processor return type
* @return result of {@link EntryProcessor#process(Map.Entry)}
* @throws NullPointerException if the specified key is {@code null}
*/
R executeOnKey(@Nonnull K key,
@Nonnull EntryProcessor entryProcessor);
/**
* Applies the user defined {@link EntryProcessor} to the entries mapped by the collection of keys.
*
* The operation is not lock-aware. The {@code EntryProcessor} will process the entries no matter if the keys are
* locked or not. For more details check Entry Processing section on {@link IMap} documentation.
*
*
Interactions with the map store
*
* For each entry not found in memory an attempt will be made
* 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, an attempt will be made 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, an attempt will be made 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
* be already succeeded on some of the keys.
*
* If write-behind persistence mode is
* configured with write-coalescing turned off,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* Performance note
*
Keep the state of {@code entryProcessor}
* small, it will be serialized and one copy will be sent to each member.
* Additionally, the {@linkplain EntryProcessor#getBackupProcessor() backup
* processor} will also be serialized once for each affected partition and
* sent to each backup. For example, in this usage the entire {@code
* additions} map will be duplicated once for each member and once for each
* partition and backup:
*
{@code
* HashMap additions = ...;
* iMap.executeOnKeys(map.keySet(), entry -> {
* Integer updateBy = additions.get(entry.getKey());
* entry.setValue(entry.getValue() + updateBy);
* return null;
* });
* }
*
* @param keys The keys to execute the entry processor on. Can be empty, in
* that case it's a local no-op
* @param the entry processor return type
* @return results of {@link EntryProcessor#process(Map.Entry)}
* @throws NullPointerException if there's null element in {@code keys}
*/
Map executeOnKeys(@Nonnull Set keys,
@Nonnull EntryProcessor entryProcessor);
/**
* Async version of {@link #executeOnKeys}.
* @param keys the keys to execute the entry processor on. Can be empty, in
* that case it's a local no-op
* @param entryProcessor the processor to process the keys
* @param return type for entry processor
* @return CompletionStage on which client code can block waiting for the
* operation to complete or register callbacks to be invoked
* upon set operation completion
* @see CompletionStage
*/
CompletionStage> submitToKeys(@Nonnull Set keys,
@Nonnull EntryProcessor entryProcessor);
/**
* Applies the user defined {@code EntryProcessor} to the entry mapped by the {@code key}.
* Returns immediately with a {@link CompletionStage} representing that task.
*
* EntryProcessor is not cancellable, so calling CompletionStage.cancel() method
* won't cancel the operation of EntryProcessor.
*
* See {@link #executeOnKey(Object, EntryProcessor)} for sync version of this method.
*
*
Interactions with the map store
*
* If value with {@code key} is not found in memory
* an attempt will be made 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, an attempt will be made 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key key to be processed
* @param entryProcessor processor to process the key
* @param return type for entry processor
* @return CompletionStage on which client code can block waiting for the
* operation to complete or register callbacks to be invoked
* upon set operation completion
* @see CompletionStage
*/
CompletionStage submitToKey(@Nonnull K key,
@Nonnull EntryProcessor entryProcessor);
/**
* Applies the user defined {@link 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 {@code EntryProcessor} will process the entries no matter if the keys are
* locked or not. For more details check Entry Processing section on {@link IMap} documentation.
*
*
Interactions with the map store
*
* For each entry not found in memory an attempt will be made
* 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, an attempt will be made 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, an attempt will be made 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
* be already succeeded on some of the keys.
*
* If write-behind persistence mode is configured with
* write-coalescing turned off,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param entryProcessor processor to process the keys
* @param return type for entry processor
* @return results mapped by entry key
*/
Map executeOnEntries(@Nonnull EntryProcessor entryProcessor);
/**
* Applies the user defined {@link 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 {@code 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, an attempt will be made 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, an attempt will be made 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param entryProcessor processor to process the keys
* @param predicate predicate to filter the entries with
* @param return type for entry processor
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
* @return results mapped by entry key
*/
Map executeOnEntries(@Nonnull EntryProcessor entryProcessor,
@Nonnull Predicate predicate);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code remappingFunction} is always executed locally
*
*
* @since 4.1
*/
V compute(@Nonnull K key, @Nonnull BiFunction remappingFunction);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code mappingFunction} is always executed locally
*
*
* @since 4.1
*/
V computeIfAbsent(@Nonnull K key, @Nonnull Function mappingFunction);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code remappingFunction} is always executed locally
*
*
* @since 4.1
*/
V computeIfPresent(@Nonnull K key, @Nonnull BiFunction remappingFunction);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code remappingFunction} is always executed locally
*
*
* @since 4.1
*/
@Override
V merge(@Nonnull K key, @Nonnull V value, @Nonnull BiFunction remappingFunction);
/**
* 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.
*
* @return an iterator for the map entries
* @since 4.2
*/
@Nonnull
@Override
Iterator> 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.
*
* @param 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.
* @return an iterator for the map entries
* @since 4.2
*/
@Nonnull
Iterator> iterator(int fetchSize);
/**
* {@inheritDoc}
*
*
*
* If the supplied {@code 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 {@code action} may not be visible to the local JVM.
* If users intend to install the changed value in the map entry, the {@link IMap#executeOnEntries(EntryProcessor)}
* method can be used instead
*
*
* When this method is invoked using a hazelcast-client instance, the {@code action} is always executed locally
*
*/
default void forEach(@Nonnull BiConsumer action) {
ConcurrentMap.super.forEach(action);
}
/**
* Returns the {@code EntryView} for the specified key.
*
* Not to misuse this method, please know these points:
*
* This method cannot be used as a replacement for {@link IMap#get}.
* This method only looks up entries already in memory and
* does not load missing ones from the map store.
* 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key of the entry
* @return {@code EntryView} of the specified key
* @throws NullPointerException if the specified key is {@code null}
* @see EntryView
*/
EntryView getEntryView(@Nonnull K key);
/**
* Asynchronously gets the given key. {@link CompletionStage} can be converted to a
* {@link java.util.concurrent.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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* // assuming an IMap
* CompletionStage future = map.getAsync("a");
* future.thenAcceptAsync(response -> System.out.println(response));
* }
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If value with {@code key} is not found in memory
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* @param key the key of the map entry
* @return CompletionStage from which the value of the key can be retrieved
* @throws NullPointerException if the specified key is null
* @see CompletionStage
*/
CompletionStage getAsync(@Nonnull K key);
/**
* Asynchronously puts the given key and value. {@link CompletionStage} can be converted to a
* {@link java.util.concurrent.CompletableFuture} to obtain the value in a blocking way:
* {@code
* CompletionStage
* Additionally, the client can register further computation stages to be invoked upon
* completion of the {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* // assuming an IMap
* CompletionStage 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
Note:
* Use {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @return CompletionStage from which the old value of the key can be retrieved
* @throws NullPointerException if the specified key or value is null
* @see CompletionStage
* @see #setAsync(Object, Object)
*/
CompletionStage putAsync(@Nonnull K key, @Nonnull V value);
/**
* 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();
*
* {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* // assuming an IMap
* CompletionStage future = map.putAsync("a", "b", 5, TimeUnit.MINUTES);
* future.thenAccept(oldVal -> System.out.println(oldVal));
* }
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative means map config default)
* @param ttlUnit time unit for the TTL
* @return CompletionStage from which the old value of the key can be retrieved
* @throws NullPointerException if the specified key or value is null
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
* @see CompletionStage
* @see #setAsync(Object, Object, long, TimeUnit)
*/
CompletionStage 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 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();
*
* {@code CompletionStage.toCompletableFuture().get()} will block until the actual map.put() completes.
* If your application requires a timely response,
* then you can use {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* // assuming an IMap
* CompletionStage future = map.putAsync("a", "b", 5, TimeUnit.MINUTES);
* future.thenAcceptAsync(oldValue -> System.out.println(oldValue));
* }
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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 {@link #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 {@code key} in memory,
* an attempt will be made to load the value from
* the map store backing the map. Exceptions thrown by the map store fail
* the operation and are propagated to the caller.
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @return CompletionStage from which the old value of the key can be retrieved
* @throws NullPointerException if the specified key, value, ttlUnit or maxIdleUnit are {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
* @see CompletionStage
* @see #setAsync(Object, Object, long, TimeUnit)
*/
CompletionStage putAsync(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* Asynchronously copies all of the mappings from the specified map to this map.
* This version doesn't support batching.
* {@code
* CompletionStage future = map.putAllAsync(map);
* // do some other stuff, when ready wait for completion
* future.toCompletableFuture.get();
* }
* {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* CompletionStage future = map.putAllAsync(map);
* future.thenRunAsync(() -> System.out.println("All the entries are added"));
* }
* {@inheritDoc}
*
* 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
* an attempt will be made to load the value from
* the map store backing the map, which may come at a significant
* performance cost. Exceptions thrown by the map 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-through persistence mode is configured,
* an attempt will be made for each element to store it
* before the element is added in memory, which may come at a
* significant performance cost. Exceptions thrown by the map 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
* @param map mappings to be stored in this map
* @return CompletionStage on which client code can block waiting for the
* operation to complete or register callbacks to be invoked
* upon putAll operation completion
* @see CompletionStage
*
* @since 4.1
*/
CompletionStage putAllAsync(@Nonnull Map map);
/**
* 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.
* {@code
* CompletionStage future = map.setAsync(key, value);
* // do some other stuff, when ready wait for completion
* future.toCompletableFuture().get();
* }
* {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* CompletionStage future = map.setAsync("a", "b");
* future.thenRunAsync(() -> System.out.println("Value is now set to b."));
* }
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If write-through persistence mode is configured, before the value
* is stored in memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @return 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 CompletionStage
*/
CompletionStage setAsync(@Nonnull K key, @Nonnull V value);
/**
* 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 {@code 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();
*
* {@code CompletionStage.toCompletableFuture().get()} will block until the actual map set operation completes.
* If your application requires a timely response,
* then you can use {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
*
* CompletionStage<Void> future = map.setAsync("a", "b", 5, TimeUnit.MINUTES);
* future.thenRunAsync(() -> System.out.println("done"));
*
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @return 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
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
* @see CompletionStage
*/
CompletionStage 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 and max idle time value without returning the old value
* (which is more efficient than {@code 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();
*
* {@code CompletionStage.toCompletableFuture().get()} will block until the actual map set operation
* completes. If your application requires a timely response,
* then you can use {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
*
* CompletionStage<Void> future = map.setAsync("a", "b", 5, TimeUnit.MINUTES);
* future.thenRunAsync(() -> System.out.println("Done"));
*
*
* Warning 1:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code 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, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key the key of the map entry
* @param value the new value of the map entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param ttlUnit time unit for the TTL
* @param maxIdle maximum time for this entry to stay idle in the map.
* (0 means infinite, negative means map config default)
* @param maxIdleUnit time unit for the Max-Idle
* @return 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 {@code null}
* @throws UnsupportedOperationException if the underlying map storage doesn't
* support TTL-based expiration (all in-memory storages support it).
* @see CompletionStage
*/
CompletionStage setAsync(@Nonnull K key, @Nonnull V value,
long ttl, @Nonnull TimeUnit ttlUnit,
long maxIdle, @Nonnull TimeUnit maxIdleUnit);
/**
* 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.
* {@code
* CompletionStage future = map.setAllAsync(map);
* // do some other stuff, when ready wait for completion
* future.toCompletableFuture.get();
* }
* {@code 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 {@code CompletionStage} via any of {@link CompletionStage}
* methods:
* {@code
* CompletionStage 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,
* an attempt will be made for each element to store it
* before the element is added in memory, which may come at a
* significant performance cost. Exceptions thrown by the map 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
* @param map mappings to be stored in this map
* @return CompletionStage on which client code can block waiting for the
* operation to complete or register callbacks to be invoked
* upon setAll operation completion
* @see CompletionStage
*
* @since 4.1
*/
CompletionStage setAllAsync(@Nonnull Map map);
/**
* Asynchronously removes the given key, returning an {@link 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
* {@link CompletionStage#toCompletableFuture()}.
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If write-through persistence mode is configured, before the value
* is removed from the memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key The key of the map entry to remove
* @return {@link CompletionStage} from which the value removed from the map can be retrieved
* @throws NullPointerException if the specified key is {@code null}
* @see CompletionStage
*/
CompletionStage removeAsync(@Nonnull K key);
/**
* Asynchronously removes the given key, returning an {@link 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
* {@link CompletionStage#toCompletableFuture()}.
*
*
* Unlike {@link #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 {@link CompletionStage} completes with a boolean value:
* {@code true} if the key is in memory and deletion is successful,
* {@code false} otherwise.
*
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form
* of the {@code key}, not the actual implementations of {@code hashCode}
* and {@code equals} defined in the {@code key}'s class.
*
*
Interactions with the map store
*
* If write-through persistence mode is configured, before the value
* is removed from the memory, an attempt will be made
* 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,
* {@link com.hazelcast.map.ReachedMaxSizeException} may be thrown
* if the write-behind queue has reached its per-node maximum
* capacity.
*
* @param key The key of the map entry to remove
* @return {@link CompletionStage} which completes with a {@code boolean} value, indicating the result of the deletion
* @throws NullPointerException if the specified key is {@code null}
* @see CompletionStage
*/
CompletionStage deleteAsync(@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
* {@code lock()} until the non-existent key is unlocked. If the lock
* holder introduces the key to the map, the {@code 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 {@code 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key key to lock
* @throws NullPointerException if the specified key is {@code null}
*/
void lock(@Nonnull K key);
/**
* 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key to lock
* @param leaseTime time to wait before releasing the lock
* @param timeUnit unit of time to specify lease time
* @throws NullPointerException if the specified key is {@code null}
* @throws IllegalArgumentException if the leaseTime is not positive
*/
void lock(@Nonnull K key, long leaseTime, @Nullable TimeUnit timeUnit);
/**
* 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key to lock
* @return {@code true} if lock is acquired, {@code false} otherwise
* @throws NullPointerException if the specified key is {@code null}
*/
boolean tryLock(@Nonnull K key);
/**
* 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key key to lock in this map
* @param time maximum time to wait for the lock
* @param timeunit time unit of the {@code time} argument
* @return {@code true} if the lock was acquired, {@code false} if the waiting time
* elapsed before the lock was acquired
* @throws NullPointerException if the specified key is {@code null}
* @throws InterruptedException if interrupted while trying to acquire the lock
*/
boolean tryLock(@Nonnull K key, long time, @Nullable TimeUnit timeunit) 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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key key to lock in this map
* @param time maximum time to wait for the lock
* @param timeunit time unit of the {@code time} argument
* @param leaseTime time to wait before releasing the lock
* @param leaseTimeunit unit of time to specify lease time
* @return {@code true} if the lock was acquired, {@code false} if the waiting time
* elapsed before the lock was acquired
* @throws NullPointerException if the specified key is {@code null}
* @throws InterruptedException if interrupted while trying to acquire the lock
*/
boolean tryLock(@Nonnull K key,
long time, @Nullable TimeUnit timeunit,
long leaseTime, @Nullable TimeUnit leaseTimeunit)
throws InterruptedException;
/**
* 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 {@link IllegalMonitorStateException} is thrown.
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key to unlock
* @throws NullPointerException if the specified key is {@code null}
* @throws IllegalMonitorStateException if the current thread does not hold this lock
*/
void unlock(@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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key to unlock
* @throws NullPointerException if the specified key is {@code null}
*/
void forceUnlock(@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 {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param key the key that is checked for lock
* @return {@code true} if lock is acquired, {@code false} otherwise
* @throws NullPointerException if the specified key is {@code null}
*/
boolean isLocked(@Nonnull K key);
/**
* Evicts the specified key from this map.
*
* If a {@code MapStore} is defined for this map, then the entry is
* not deleted from the underlying {@code MapStore}, evict only
* removes the entry from the memory. Use {@link #delete(Object)} or
* {@link #remove(Object)} to delete the element from the map store.
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the
* binary form of the {@code key}, not the actual implementations of
* {@code hashCode} and {@code equals} defined in the {@code key}'s
* class.
*
* @param key the specified key to evict from this map
* @return {@code true} if the key is evicted, {@code false} otherwise
* @throws NullPointerException if the specified key is {@code null}
* @see #delete(Object)
* @see #remove(Object)
*/
boolean evict(@Nonnull K key);
/**
* Evicts all keys from this map except the locked ones.
*
* If a {@code MapStore} is defined for this map, the entries are
* not deleted from the map store by this method. If you do want to
* delete all the entries from the map store use the
* {@link #clear()} method.
*
* The EVICT_ALL event is fired for any registered listeners.
* See {@link com.hazelcast.core.EntryListener#mapEvicted(MapEvent)} .
*
* @see #clear()
* @since 3.3
*/
void evictAll();
/**
* 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 {@link 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.
*
* @return this map's local statistics
*/
LocalMapStats getLocalMapStats();
/**
* Updates the TTL (time to live) value of the entry specified by {@code 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 {@code 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.
*
* @param key the key of the map entry
* @param ttl maximum time for this entry to stay in the map (0 means infinite, negative
* means map config default)
* @param timeunit time unit for the TTL
* @return {@code true} if the entry exists and its ttl value is changed, {@code false} otherwise
* @throws NullPointerException if the specified {@code key} or {@code timeunit} is {@code null}.
* @since 3.11
*/
boolean setTtl(@Nonnull K key, long ttl, @Nonnull TimeUnit timeunit);
/**
* If this map has a MapStore, this method flushes
* all the local dirty entries.
*
*
Interactions with the map store
*
* Stores and/or deletes all 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.
*/
void flush();
/**
* 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
*
* Loads all keys from the map store and with the loaded keys
* loads all elements on each
* partition. Exceptions thrown by the map store are
* not propagated to the caller.
*
* @param replaceExistingValues when {@code true}, existing values
* in the Map will be replaced by those
* loaded from the MapLoader
* @since 3.3
*/
void loadAll(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
*
* Loads all elements on the
* partitions storing the values with the keys. Exceptions thrown by
* the map store are not propagated to the caller.
*
* @param keys keys of the values entries to load (keys inside the collection cannot be null)
* @param replaceExistingValues when {@code true}, existing values in the Map will
* be replaced by those loaded from the MapLoader
* @since 3.3
*/
void loadAll(@Nonnull Set keys, boolean replaceExistingValues);
/**
* Convenient method to add an index to this map with the given type and attributes.
* Attributes are indexed in ascending order.
*
*
* @param type Index type.
* @param attributes Attributes to be indexed.
* @see #addIndex(IndexConfig)
*/
default void addIndex(IndexType type, String... attributes) {
IndexConfig config = IndexUtils.createIndexConfig(type, attributes);
addIndex(config);
}
/**
* 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.
*
* @param indexConfig Index configuration.
*/
void addIndex(IndexConfig indexConfig);
/**
* 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.
*
* @param interceptor map interceptor
* @return ID of registered interceptor
*/
String addInterceptor(@Nonnull MapInterceptor interceptor);
/**
* Removes the given interceptor for this map,
* so it will not intercept operations anymore.
*
* @param id registration ID of the map interceptor
* @return {@code true} if registration is removed, {@code false} otherwise
*/
boolean removeInterceptor(@Nonnull String id);
/**
* Adds a {@link MapListener} for this map.
*
* To receive an event, you should implement a corresponding {@link MapListener}
* sub-interface for that event.
*
* @param listener {@link MapListener} for this map
* @param includeValue {@code true} if {@code EntryEvent} should contain the value
* @return a UUID.randomUUID().toString() which is used as a key to remove the listener
* @throws NullPointerException if the specified listener is {@code null}
* @see MapListener
*/
UUID addEntryListener(@Nonnull MapListener listener, boolean includeValue);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* Warning:
*
* This method uses {@code hashCode} and {@code equals} of the binary form of
* the {@code key}, not the actual implementations of {@code hashCode} and {@code equals}
* defined in the {@code key}'s class.
*
* @param listener {@link MapListener} for this map
* @param key key to listen for
* @param includeValue {@code true} if {@code EntryEvent} should contain the value
* @return a UUID.randomUUID().toString() which is used as a key to remove the listener
* @throws NullPointerException if the specified listener is {@code null}
* @throws NullPointerException if the specified key is {@code null}
* @see MapListener
*/
UUID addEntryListener(@Nonnull MapListener listener, @Nonnull K key, boolean includeValue);
/**
* Adds a {@link MapListener} for this map.
*
* To receive an event, you should implement a corresponding {@link MapListener}
* sub-interface for that event.
*
* @param listener the added continuous {@link MapListener} for this map
* @param predicate predicate for filtering entries
* @param includeValue {@code true} if {@code EntryEvent} should contain the value
* @return a UUID.randomUUID().toString() which is used as a key to remove the listener
* @throws NullPointerException if the specified {@code listener} or {@code predicate}
* is {@code null}
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
* @see MapListener
*/
UUID addEntryListener(@Nonnull MapListener listener,
@Nonnull Predicate predicate,
boolean includeValue);
/**
* Adds a {@link MapListener} for this map.
*
* To receive an event, you should implement a corresponding {@link MapListener} sub-interface for that event.
*
* @param listener the continuous {@link MapListener} for this map
* @param predicate predicate for filtering entries
* @param key key to listen for
* @param includeValue {@code true} if {@code EntryEvent} should contain the value
* @return a UUID.randomUUID().toString() which is used as a key to remove the listener
* @throws NullPointerException if the specified {@code listener} or {@code predicate} is {@code null}
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
* @see MapListener
*/
UUID addEntryListener(@Nonnull MapListener listener,
@Nonnull Predicate predicate,
@Nullable K key,
boolean includeValue);
/**
* Removes the specified entry listener.
*
* Returns silently if there is no such listener added before.
*
* @param id ID of registered listener
* @return true if registration is removed, false otherwise
*/
boolean removeEntryListener(@Nonnull UUID id);
/**
* Adds a MapPartitionLostListener.
*
* The method returns a register ID. This ID is needed to remove the
* {@link MapPartitionLostListener} using the
* {@link #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 {@link com.hazelcast.partition.PartitionLostListener} for weaknesses.
*
* Warning 2:
*
* Listeners registered from HazelcastClient may miss some of the map
* partition lost events due to design limitations.
*
* @param listener the added MapPartitionLostListener
* @return returns the registration ID for the MapPartitionLostListener
* @throws java.lang.NullPointerException if listener is {@code null}
* @see #removePartitionLostListener(UUID)
* @see com.hazelcast.partition.PartitionLostListener
*/
UUID addPartitionLostListener(@Nonnull MapPartitionLostListener listener);
/**
* Removes the specified map partition lost listener.
*
* Returns silently if there is no such listener was added before.
*
* @param id ID of registered listener
* @return true if registration is removed, false otherwise
* @throws NullPointerException if {@code id} is {@code null}
*/
boolean removePartitionLostListener(@Nonnull UUID id);
/**
* 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.
*
* @param aggregator aggregator to aggregate the entries with
* @param type of the result
* @return the result of the given type
* @since 3.8
*/
R aggregate(@Nonnull Aggregator, R> aggregator);
/**
* 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.
*
* @param aggregator aggregator to aggregate the entries with
* @param predicate predicate to filter the entries with
* @param type of the result
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
* @return the result of the given type
* @since 3.8
*/
R aggregate(@Nonnull Aggregator, R> aggregator,
@Nonnull Predicate predicate);
/**
* Applies the projection logic on all map entries and returns the result
*
* @param projection projection to transform the entries with (may return null)
* @param type of the result
* @return the result of the given type
* @since 3.8
*/
Collection project(@Nonnull Projection, R> projection);
/**
* Applies the projection logic on map entries filtered with the Predicated and returns the result
*
* @param projection projection to transform the entries with (may return null)
* @param predicate predicate to filter the entries with
* @param type of the result
* @throws IllegalArgumentException if the predicate is a {@link com.hazelcast.query.PagingPredicate} or is a
* {@link com.hazelcast.query.PartitionPredicate} that includes a
* {@link com.hazelcast.query.PagingPredicate}
* @return the result of the given type
* @since 3.8
*/
Collection project(@Nonnull Projection, R> projection,
@Nonnull Predicate predicate);
}