com.hazelcast.core.MultiMap Maven / Gradle / Ivy
Show all versions of hazelcast-all Show documentation
/*
* Copyright (c) 2008-2019, 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.mapreduce.JobTracker;
import com.hazelcast.mapreduce.aggregation.Aggregation;
import com.hazelcast.mapreduce.aggregation.Supplier;
import com.hazelcast.monitor.LocalMultiMapStats;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;
/**
* A specialized map whose keys can be associated with multiple values.
*
* Gotchas:
*
* -
* Methods -- including but not limited to {@code get}, {@code containsKey},
* {@code containsValue}, {@code remove}, {@code put},
* {@code lock}, and {@code unlock} -- do not use {@code hashCode} and {@code equals}
* implementations of the keys.
* Instead, they use {@code hashCode} and {@code equals} of the binary (serialized) forms of the objects.
*
* -
* Methods -- including but not limited to {@code get}, {@code remove},
* {@code keySet}, {@code values}, {@code entrySet} --
* return a collection clone of the values. The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection, and vice-versa.
*
*
*
* Supports Quorum {@link com.hazelcast.config.QuorumConfig} since 3.10 in cluster versions 3.10 and higher.
*
* @param type of the multimap key
* @param type of the multimap value
* @see IMap
*/
@SuppressWarnings("checkstyle:methodcount")
public interface MultiMap extends BaseMultiMap {
/**
* Stores a key-value pair in the multimap.
*
* 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 be stored
* @param value the value to be stored
* @return {@code true} if size of the multimap is increased,
* {@code false} if the multimap already contains the key-value pair
*/
boolean put(K key, V value);
/**
* Returns the collection of values associated with the key.
*
* 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: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @param key the key whose associated values are to be returned
* @return the collection of the values associated with the key
*/
Collection get(K key);
/**
* Removes the given key value pair from the multimap.
*
* 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 of the entry to remove
* @param value the value of the entry to remove
* @return {@code true} if the size of the multimap changed after the remove operation,
* {@code false} otherwise
*/
boolean remove(Object key, Object value);
/**
* Removes all the entries with the given key.
*
* 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: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @param key the key of the entries to remove
* @return the collection of removed values associated with the given key.
* The returned collection might be modifiable but it has no effect on the multimap.
*/
Collection remove(Object key);
/**
* Deletes all the entries with the given key.
*
* 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 of the entry to remove
*/
void delete(Object key);
/**
* Returns the locally owned set of keys.
*
* Each key in this map is owned and managed by a specific member in the
* cluster.
*
* Note that ownership of these keys might change over time so that key
* ownerships can be almost evenly distributed in the cluster.
*
* Warning: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @return the locally owned keys
*/
Set localKeySet();
/**
* Returns the set of keys in the multimap.
*
* Warning: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @return the set of keys in the multimap (the returned set might be
* modifiable but it has no effect on the multimap)
*/
Set keySet();
/**
* Returns the collection of values in the multimap.
*
* Warning: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @return the collection of values in the multimap (the returned
* collection might be modifiable but it has no effect on the multimap)
*/
Collection values();
/**
* Returns the set of key-value pairs in the multimap.
*
* Warning: The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection,
* and vice-versa.
*
* @return the set of key-value pairs in the multimap (the returned
* set might be modifiable but it has no effect on the multimap)
*/
Set> entrySet();
/**
* Returns whether the multimap contains an entry with the key.
*
* 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 whose existence is checked
* @return {@code true} if the multimap contains an entry with the key,
* {@code false} otherwise
*/
boolean containsKey(K key);
/**
* Returns whether the multimap contains an entry with the value.
*
* @param value the value whose existence is checked
* @return {@code true} if the multimap contains an entry with the value,
* {@code false} otherwise.
*/
boolean containsValue(Object value);
/**
* Returns whether the multimap contains the given key-value pair.
*
* 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 whose existence is checked
* @param value the value whose existence is checked
* @return {@code true} if the multimap contains the key-value pair,
* {@code false} otherwise
*/
boolean containsEntry(K key, V value);
/**
* Returns the number of key-value pairs in the multimap.
*
* @return the number of key-value pairs in the multimap
*/
int size();
/**
* Clears the multimap. Removes all key-value pairs.
*/
void clear();
/**
* Returns the number of values that match the given key in the multimap.
*
* 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 whose values count is to be returned
* @return the number of values that match the given key in the multimap
*/
int valueCount(K key);
/**
* Adds a local entry listener for this multimap.
*
* The added listener will be only listening for the events
* (add/remove/update) of the locally owned entries.
*
* Note that entries in distributed multimap are partitioned across the
* cluster members; each member owns and manages some portion of the
* entries. Owned entries are called local entries. This listener will be
* listening for the events of local entries.
*
* For example your cluster has member1 and member2. On member2 you added a
* local listener, and from member1, you call {@code multimap.put(key2, value2)}.
* If the key2 is owned by member2, then the local listener will be notified
* for the add/update event. Also note that entries can migrate to other
* nodes for load balancing and/or membership change.
*
* @param listener entry listener for this multimap
* @return returns registration ID for the entry listener
* @see #localKeySet()
*/
String addLocalEntryListener(EntryListener listener);
/**
* Adds an entry listener for this multimap.
*
* The listener will be notified for all multimap
* add/remove/update/evict events.
*
* @param listener entry listener for this multimap
* @param includeValue {@code true} if {@code EntryEvent} should contain the value,
* {@code false} otherwise
* @return returns registration ID for the entry listener
*/
String addEntryListener(EntryListener listener, boolean includeValue);
/**
* Removes the specified entry listener.
*
* Returns silently if no such listener was added before.
*
* @param registrationId registration ID of listener
* @return true if registration is removed, false otherwise
*/
boolean removeEntryListener(String registrationId);
/**
* Adds the specified entry listener for the specified key.
*
* The listener will be notified for all add/remove/update/evict events for
* the specified key only.
*
* 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 the entry listener
* @param key the key to listen to
* @param includeValue {@code true} if {@code EntryEvent} should contain the value,
* {@code false} otherwise
* @return returns registration ID
*/
String addEntryListener(EntryListener listener, K key, boolean includeValue);
/**
* Acquires a 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.
*
* The scope of the lock is for this multimap only. The acquired lock is
* only for the key in this multimap.
*
* 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
*/
void lock(K key);
/**
* Acquires the lock for the specified key for the specified lease time.
*
* After the 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 for this map only.The 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 for the lease time
*/
void lock(K key, long leaseTime, TimeUnit timeUnit);
/**
* Checks the lock for the specified key.
*
* If the lock is acquired, this method returns {@code true}, else it
* returns {@code 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 key to lock to be checked.
* @return {@code true} if the lock is acquired, {@code false} otherwise.
*/
boolean isLocked(K key);
/**
* Tries to acquire the lock for the specified key.
*
* If the lock is not available, then the current thread does not wait and
* the method 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
*/
boolean tryLock(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 time the maximum time to wait for the lock
* @param timeunit the 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
*/
boolean tryLock(K key, long time, 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 and {@code false} if the
* waiting time elapsed before the lock was acquired
* @throws NullPointerException if the specified key is {@code null}
*/
boolean tryLock(K key, long time, TimeUnit timeunit, long leaseTime, TimeUnit leaseTimeunit) throws InterruptedException;
/**
* Releases the lock for the specified key.
*
* It 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 lock
*/
void unlock(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 key to lock
*/
void forceUnlock(K key);
/**
* Returns {@code LocalMultiMapStats} for this map.
*
* {@code LocalMultiMapStats} is the statistics for the local portion of this
* distributed multi map and contains information such as ownedEntryCount
* backupEntryCount, lastUpdateTime, and lockedEntryCount.
*
* Since this stats are only for the local portion of this multi map, if you
* need the cluster-wide MultiMapStats, then you need to get the {@link com.hazelcast.monitor.LocalMapStats LocalMapStats}
* from all members of the cluster and combine them.
*
* @return this multimap's local statistics.
*/
LocalMultiMapStats getLocalMultiMapStats();
/**
* Executes a predefined aggregation on the multimaps data set.
*
* The {@link com.hazelcast.mapreduce.aggregation.Supplier} is used to
* either select or to select and extract a (sub-)value.
* A predefined set of aggregations can be found in
* {@link com.hazelcast.mapreduce.aggregation.Aggregations}.
*
* Method does not honor Quorum.
*
* @param supplier the supplier to select and / or extract a (sub-)value from the multimap
* @param aggregation the aggregation that is being executed against the multimap
* @param the final type emitted from the supplier
* @param the resulting aggregation value type
* @return Returns the aggregated value for the multimaps data set
* @deprecated The old Aggregations API is superseded by Fast Aggregations ({@link com.hazelcast.aggregation})
* which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
*/
@Deprecated
Result aggregate(Supplier supplier,
Aggregation aggregation);
/**
* Executes a predefined aggregation on the multimaps data set.
*
* The {@link com.hazelcast.mapreduce.aggregation.Supplier} is used to
* either select, or to select and extract, a (sub-)value.
* A predefined set of aggregations can be found in
* {@link com.hazelcast.mapreduce.aggregation.Aggregations}.
*
* Method does not honor Quorum.
*
* @param supplier the supplier to select and / or extract a (sub-)value from the multimap
* @param aggregation the aggregation that is being executed against the multimap
* @param jobTracker the {@link com.hazelcast.mapreduce.JobTracker} instance to execute the aggregation
* @param the final type emitted from the supplier
* @param the resulting aggregation value type
* @return Returns the aggregated value
* @deprecated The old Aggregations API is superseded by Fast Aggregations ({@link com.hazelcast.aggregation})
* which does not yet support MultiMap. Hazelcast Jet can be used in the future to replace this functionality.
*/
@Deprecated
Result aggregate(Supplier supplier,
Aggregation aggregation,
JobTracker jobTracker);
}