com.hazelcast.replicatedmap.ReplicatedMap 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.replicatedmap;
import com.hazelcast.core.DistributedObject;
import com.hazelcast.core.EntryListener;
import com.hazelcast.query.Predicate;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Collection;
import java.util.Comparator;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import java.util.concurrent.TimeUnit;
/**
* A ReplicatedMap is a map data structure with weak consistency
* and has entries stored locally on every node of the cluster.
*
*
Whenever a value is written, the new value will be internally
* distributed to all existing cluster members, and eventually every node
* will have the new value. Reading is always local on members (except
* for lite members).
*
*
When a new node joins the cluster, it initially requests existing
* values from older nodes and replicates them locally.
*
*
Supports split-brain protection in cluster versions 3.10 and higher.
*
* @param the type of keys maintained by this map
* @param the type of mapped values
* @since 3.2
*/
public interface ReplicatedMap extends Map, DistributedObject {
/**
* Associates a given value to the specified key and replicates it to the
* cluster. If there is an old value, it will be replaced by the specified
* one and returned from the call.
*
In addition, you have to specify a ttl and its {@link TimeUnit}
* to define when the value is outdated and thus should be removed from the
* replicated map.
*
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
* @param ttl ttl to be associated with the specified key-value pair.
* @param timeUnit TimeUnit to be used for the ttl value.
*/
V put(@Nonnull K key, @Nonnull V value, long ttl, @Nonnull TimeUnit timeUnit);
/**
*
The clear operation wipes data out of the replicated maps.
*
If some node fails on executing the operation, it is retried for at most
* 5 times (on the failing nodes only).
*/
void clear();
/**
* Removes the specified entry listener.
* Returns silently if there was no such listener added before.
*
* @param id ID of the registered entry listener.
* @return true if registration is removed, false otherwise.
*/
boolean removeEntryListener(@Nonnull UUID id);
/**
* Adds an entry listener for this map. The listener will be notified
* for all map add/remove/update/evict events.
*
* @param listener entry listener
*/
@Nonnull
UUID addEntryListener(@Nonnull EntryListener listener);
/**
* Adds the specified entry listener for the specified key.
* The listener will be notified for all
* add/remove/update/evict events of the specified key only.
* Warning:
* This method uses hashCode and equals of the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @param listener the entry listener to add
* @param key the key to listen to
* @throws NullPointerException if the specified key is null
*/
@Nonnull
UUID addEntryListener(@Nonnull EntryListener listener, @Nullable K key);
/**
* Adds a continuous entry listener for this map. The listener will be notified
* for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener the entry listener to add
* @param predicate the predicate for filtering entries
*/
@Nonnull
UUID addEntryListener(@Nonnull EntryListener listener, @Nonnull Predicate predicate);
/**
* Adds a continuous entry listener for this map. The listener will be notified
* for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener the entry listener
* @param predicate the predicate for filtering entries
* @param key the key to listen to
*/
@Nonnull
UUID addEntryListener(@Nonnull EntryListener listener,
@Nonnull Predicate predicate,
@Nullable K key);
/**
* Returns a lazy {@link Collection} view of the values contained in this map.
* A LazyCollection is optimized for querying speed (preventing eager deserialization
* and hashing on HashSet insertion) and does NOT provide all operations.
* Any kind of mutating function will throw an
* {@link UnsupportedOperationException}. Same is true for operations
* like {@link Collection#contains(Object)} and
* {@link Collection#containsAll(Collection)}, which would result in
* very poor performance if called repeatedly (for example, in a loop). If the use
* case is different from querying the data, please copy the resulting set into a
* new {@link java.util.List} or similar data structure.
*
* ReplicatedMap<K, V> repMap = ...;
* // Returns a LazyCollection
* Collection<V> values = repMap.values();
* List<V> copy = new ArrayList<V>(values);
* if (copy.containsAll(possibleValues)) {
* // ...
* }
*
* Due to the lazy nature of the returned set, changes to the map (addition,
* removal, update) might be reflected on the collection.
* Changes on the map are NOT reflected on the collection on the CLIENT or vice versa.
* The order of the elements is not guaranteed due to the internal
* asynchronous replication behavior. If a specific order is needed, use
* {@link #values(Comparator)} to force reordering of the
* elements before returning.
* Changes to any returned object are NOT replicated back to other
* members.
*
* @return A collection view of the values contained in this map.
*/
@Nonnull
Collection values();
/**
* Returns an eagerly populated {@link Collection} view of the values contained in this map.
* The collection is NOT backed by the map, so changes to the map are
* NOT reflected on the collection, and vice-versa.
* The order of the elements is guaranteed by executing the given
* {@link Comparator} before returning the elements.
* Changes to any returned object are NOT replicated back to other
* members.
*
* @param comparator the Comparator to sort the returned elements.
* @return An eagerly populated {@link Collection} view of the values contained in this map.
*/
@Nonnull
Collection values(@Nullable Comparator comparator);
/**
* Returns a lazy {@link Set} view of the mappings contained in this map.
* A LazySet is optimized for querying speed (preventing eager deserialization
* and hashing on HashSet insertion) and does NOT provide all operations.
* Any kind of mutating function will throw an
* {@link UnsupportedOperationException}. Same is true for operations
* like {@link Set#contains(Object)} and
* {@link Set#containsAll(Collection)} which would result in
* very poor performance if called repeatedly (for example, in a loop). If the use
* case is different from querying the data, please copy the resulting set into a
* new {@link java.util.HashSet}.
*
* ReplicatedMap<K, V> repMap = ...;
* // Returns a LazySet
* Set<Map.Entry<K, V>> entrySet = repMap.entrySet();
* Set<Map.Entry<K, V>> copy = new HashSet<Map.Entry<K, V>>(entrySet);
*
* Due to the lazy nature of the returned set, changes to the map (addition,
* removal, update) might be reflected on the set.
* Changes on the map are NOT reflected on the set on the CLIENT or vice versa.
* The order of the elements is not guaranteed due to the internal
* asynchronous replication behavior.
* Changes to any returned object are NOT replicated back to other
* members.
*
* @return A lazy set view of the mappings contained in this map.
*/
@Nonnull
Set> entrySet();
/**
* Returns a lazy {@link Set} view of the key contained in this map.
* A LazySet is optimized for querying speed (preventing eager deserialization
* and hashing on HashSet insertion) and does NOT provide all operations.
* Any kind of mutating function will throw an
* {@link UnsupportedOperationException}. Same is true for operations
* like {@link Set#contains(Object)} and
* {@link Set#containsAll(Collection)} which would result in
* very poor performance if called repeatedly (for example, in a loop). If the use
* case is different from querying the data, please copy the resulting set into a
* new {@link java.util.HashSet}.
*
* ReplicatedMap<K, V> repMap = ...;
* // Returns a LazySet
* Set<K> keySet = repMap.keySet();
* Set<K> copy = new HashSet<K>(keySet);
* for (K key : possibleKeys) {
* if (!copy.contains(key))
* return false;
* }
*
*
* Due to the lazy nature of the returned set, changes to the map (addition,
* removal, update) might be reflected on the set.
* Changes on the map are NOT reflected on the set on the CLIENT or vice versa.
* The order of the elements is not guaranteed due to the internal
* asynchronous replication behavior.
* Changes to any returned object are NOT replicated back to other
* members.
*
* @return A lazy {@link Set} view of the keys contained in this map.
*/
@Nonnull
Set keySet();
}