com.hazelcast.core.ReplicatedMap Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2018, 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.core;
import com.hazelcast.monitor.LocalReplicatedMapStats;
import com.hazelcast.query.Predicate;
import java.util.Collection;
import java.util.Comparator;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;
/**
* A ReplicatedMap is a map-like data structure with weak consistency
* and values locally stored on every node of the cluster.
* Whenever a value is written asynchronously, the new value will be internally
* distributed to all existing cluster members, and eventually every node will have
* the new value.
* When a new node joins the cluster, the new node initially will request existing
* values from older nodes and replicate them locally.
*
* Supports Quorum {@link com.hazelcast.config.QuorumConfig} since 3.10 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(K key, V value, long ttl, 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(String 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
*/
String addEntryListener(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
*/
String addEntryListener(EntryListener listener, K key);
/**
* Adds an 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
*/
String addEntryListener(EntryListener listener, Predicate predicate);
/**
* Adds an 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
*/
String addEntryListener(EntryListener listener, Predicate predicate, 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 java.lang.UnsupportedOperationException}. Same is true for operations
* like {@link java.util.Collection#contains(Object)} and
* {@link java.util.Collection#containsAll(java.util.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(java.util.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.
*/
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 java.util.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.
*/
Collection values(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 java.lang.UnsupportedOperationException}. Same is true for operations
* like {@link java.util.Set#contains(Object)} and
* {@link java.util.Set#containsAll(java.util.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.
*/
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 java.lang.UnsupportedOperationException}. Same is true for operations
* like {@link java.util.Set#contains(Object)} and
* {@link java.util.Set#containsAll(java.util.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.
*/
Set keySet();
/**
* Returns LocalReplicatedMapStats for this replicated map.
* LocalReplicatedMapStats is the statistics for the local
* replicated map and contains information such as getCount
* putCount, hits, lastUpdateTime etc.
*
*
* @return this replicated map's statistics.
*/
LocalReplicatedMapStats getReplicatedMapStats();
}