com.hazelcast.map.IMap Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hazelcast-all Show documentation
Kubernetes Service Discovery for Hazelcast Discovery SPI
There is a newer version: 62
/*
 * Copyright (c) 2008-2020, 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.config.MaxSizePolicy;
import com.hazelcast.core.EntryView;
import com.hazelcast.core.Offloadable;
import com.hazelcast.core.ReadOnly;
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 jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;
import java.util.Collection;
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.
 * Since Hazelcast is compiled with Java 1.6, we can't override default
 * methods introduced in later Java versions, nor can we add documentation
 * to them. Methods, including but not limited to {@code computeIfPresent},
 * may behave incorrectly if the value passed to the update function is
 * modified in-place and returned as a result of the invocation.
 * You should create a new value instance and return it as a result.
 * 
 * For example, following code fragment will behave incorrectly and will
 * enter an infinite loop:
 * 
 * map.computeIfPresent("key", (key, value) -> {
 *     value.setSomeAttribute("newAttributeValue");
 *     return value;
 * });
 * 
 * It should be replaced with:
 *  * map.computeIfPresent("key", (key, value) -> {
 *     return new ObjectWithSomeAttribute("newAttributeValue");
 * });
 * 
 * 
 * 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.
 * The user may however check if an entry is locked by casting the
 * {@link Map.Entry} to {@link LockAware} and invoking the
 * {@link LockAware#isLocked()} method.
 * 
 * {@link IMap#executeOnEntries(EntryProcessor)}
 * {@link IMap#executeOnEntries(EntryProcessor, Predicate)}
 * {@link IMap#executeOnKeys(Set, EntryProcessor)}
 * 
 * This applies to both {@code EntryProcessor} and {@code BackupEntryProcessor}.
 *
 * 
 * Split-brain
 * 

 * Behaviour of {@link IMap} under split-brain scenarios should be taken
 * into account when using this data structure.  During a split, each
 * partitioned cluster will either create a brand new {@link IMap} or it
 * will continue to use the primary or back-up version.
 * 

 * When the split heals, Hazelcast by default, performs a
 * {@link com.hazelcast.spi.merge.PutIfAbsentMergePolicy}.
 * Users can also decide to
 * 
 * specify their own map merge policies, these policies when used in
 * concert with
 * CRDTs (Convergent and Commutative
 * Replicated Data Types) can ensure against data loss during a split-brain.
 * 

 * As a defensive mechanism against such inconsistency, consider using the
 * in-built
 * 
 * split-brain protection for {@link IMap}.  Using this functionality
 * it is possible to restrict operations in smaller partitioned clusters.
 * It should be noted that there is still an inconsistency window between
 * the time of the split and the actual detection. Therefore using this
 * reduces the window of inconsistency but can never completely eliminate
 * it.
 *
 * 
Interactions with the map store
 * 

 * Maps can be configured to be backed by a map store to persist the entries.
 * In this case many of the IMap methods call {@link MapLoader} or
 * {@link MapStore} methods to load, store or remove data. Each method's
 * javadoc describes the way of its interaction with the map store.
 *
 * 
Expiration and eviction
 * 

 * Expiration puts a limit on the maximum lifetime of an entry stored
 * inside the map. When the entry expires it can't be retrieved from the map
 * any longer and at some point in time it will be cleaned out from the map
 * to free up the memory. There are two expiration policies:
 * 

 * The time-to-live (TTL) expiration policy limits the lifetime of the
 * entry relative to the time of the last write access performed on
 * the entry. The default TTL value for the map may be configured using
 * the {@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
 * {@link MaxSizePolicy max-size} setting
 * and the eviction policy may be configured using the
 * {@link com.hazelcast.config.EvictionPolicy 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
 */
public interface IMap extends ConcurrentMap, BaseMap {

    /**
     * {@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
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map, which may come at a significant
     * performance cost. Exceptions thrown by load fail the operation
     * and are propagated to the caller. The elements which were added
     * before the exception was thrown will remain in the map, the rest
     * will not be added.
     * 

     * If write-through persistence mode is configured,
     * {@link MapStore#store(Object, Object)} is invoked for each element
     * before the element is added in memory, which may come at a
     * significant performance cost. Exceptions thrown by store fail the
     * operation and are propagated to the caller. The elements which
     * were added before the exception was thrown will remain in the map,
     * the rest will not be added.
     * 

     * If write-behind persistence mode is configured with
     * write-coalescing turned off,
     * {@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:
     * 

     * 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
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by load fail
     * the operation and are propagated to the caller.
     *
     * @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);

    /**
     * {@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
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by load fail
     * the operation and are propagated to the caller.
     *
     * @throws NullPointerException if the specified key is {@code null}
     */
    V get(@Nonnull Object key);

    /**
     * {@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,
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by load fail
     * the operation and are propagated to the caller.
     * 

     * If write-through persistence mode is configured, before the value
     * is stored in memory, {@link MapStore#store(Object, Object)} is
     * called to write the value into the map store. Exceptions thrown
     * by store fail the operation and are propagated to the caller.
     * 

     * If write-behind persistence mode is configured with
     * write-coalescing turned off,
     * {@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);

    /**
     * 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,
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by load fail
     * the operation and are propagated to the caller.
     * 

     * If write-through persistence mode is configured, before the value
     * is removed from the memory, {@link MapStore#delete(Object)} is
     * called to remove the value from the map store. Exceptions thrown
     * by delete fail the operation and are propagated to the caller.
     * 

     * If write-behind persistence mode is configured with
     * write-coalescing turned off,
     * {@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,
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by load fail
     * the operation and are propagated to the caller.
     * 

     * If write-through persistence mode is configured, before the value
     * is removed from the memory, {@link MapStore#delete(Object)} is
     * called to remove the value from the map store. Exceptions thrown
     * by delete fail the operation and are propagated to the caller.
     * 

     * If write-behind persistence mode is configured with
     * write-coalescing turned off,
     * {@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, {@link MapStore#delete(Object)} is called to
     * remove the value from the map store. Exceptions thrown by delete fail
     * the operation and are propagated to the caller.
     * 

     * If write-behind persistence mode is configured with write-coalescing
     * turned off, {@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
     */
    void removeAll(@Nonnull Predicate predicate);

    /**
     * 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 the memory, {@link MapStore#delete(Object)}
     * is called to remove the value from the map store. Exceptions
     * thrown by delete fail the operation and are propagated to the
     * caller.
     * 

     * If write-behind persistence mode is configured with
     * write-coalescing turned off,
     * {@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);

    /**
     * If this map has a MapStore, this method flushes
     * all the local dirty entries.
     *
     * 
Interactions with the map store
     * 

     * Calls {@link MapStore#storeAll(Map)} and/or
     * {@link MapStore#deleteAll(Collection)} with elements marked dirty.
     * 

     * Please note that this method has effect only if write-behind
     * persistence mode is configured. If the persistence mode is
     * write-through calling this method has no practical effect, but an
     * operation is executed on all partitions wasting resources.
     */
    void flush();

    /**
     * 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, {@link MapLoader#loadAll}
     * is called with the missing keys. Exceptions thrown by
     * loadAll 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
     *                              from {@link MapLoader#loadAll} is {@code null}.
     */
    Map getAll(@Nullable Set keys);

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

     * Calls {@link MapLoader#loadAllKeys()} and with the loaded keys
     * calls {@link MapLoader#loadAll(java.util.Collection)} on each
     * partition. Exceptions thrown by loadAllKeys() or loadAll() 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
     * 

     * Calls {@link MapLoader#loadAll(java.util.Collection)} on the
     * partitions storing the values with the keys. Exceptions thrown by
     * loadAll() 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);

    /**
     * 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
     * 

     * Calls {@link MapStore#deleteAll(Collection)} on each partition
     * with the keys that the given partition stores. Exceptions thrown
     * by deleteAll() are not propagated to the caller.
     *
     * @see #evictAll
     */
    @Override
    void clear();

    /**
     * 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
     * {@link MapLoader#load(Object)} is invoked to load the value from
     * the map store backing the map. Exceptions thrown by {@code load} 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