com.hazelcast.core.MultiMap Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2013, 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 get, containsKey,
* containsValue, remove, put,
* lock, unlock, do not use hashCode and equals
* implementations of keys,
* instead they use hashCode and equals of binary (serialized) forms of the objects.
*
* -
* Methods, including but not limited to get, remove,
* keySet, values, 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.
*
*
*
*
* @author oztalip
* @see IMap
*/
public interface MultiMap
extends BaseMultiMap, DistributedObject {
/**
* Returns the name of this multimap.
*
* @return the name of this multimap
*/
String getName();
/**
* Stores a key-value pair in the multimap.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key the key to be stored
* @param value the value to be stored
* @return true if size of the multimap is increased, 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:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
* @param key the key of the entry to remove
* @param value the value of the entry to remove
* @return true if the size of the multimap changed after the remove operation, false otherwise.
*/
boolean remove(Object key, Object value);
/**
* Removes all the entries with the given key.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in 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. Returned collection
* might be modifiable but it has no effect on the multimap
*/
Collection remove(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 set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* @return locally owned keys.
*/
Set localKeySet();
/**
* Returns the set of keys in the multimap.
*
* Warning:
* The set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* @return the set of keys in the multimap. 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. 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 set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* @return the set of key-value pairs in the multimap. 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key the key whose existence is checked.
* @return true if the multimap contains an entry with the key, 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 true if the multimap contains an entry with the value, false otherwise.
*/
boolean containsValue(Object value);
/**
* Returns whether the multimap contains the given key-value pair.
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
* @param key the key whose existence is checked.
* @param value the value whose existence is checked.
* @return true if the multimap contains the key-value pair, 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 number of values matching to given key in the multimap.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key the key whose values count are to be returned
* @return number of values matching to given key in the multimap.
*/
int valueCount(K key);
/**
* Adds a local entry listener for this multimap. 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 the some portion of the
* entries. Owned entries are called local entries. This
* listener will be listening for the events of local entries. Let's say
* your cluster has member1 and member2. On member2 you added a local listener and from
* member1, you call 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
* @return returns registration id.
* @see #localKeySet()
*/
String addLocalEntryListener(EntryListener listener);
/**
* Adds an entry listener for this multimap. Listener will get notified
* for all multimap add/remove/update/evict events.
*
* @param listener entry listener
* @param includeValue true if EntryEvent should
* contain the value.
* @return returns registration id.
*/
String addEntryListener(EntryListener listener, boolean includeValue);
/**
* Removes the specified entry listener
* Returns silently if there is no such listener added before.
*
* @param registrationId Id of listener registration
* @return true if registration is removed, false otherwise
*/
boolean removeEntryListener(String registrationId);
/**
* Adds the specified entry listener for the specified key.
* The listener will get notified for all
* add/remove/update/evict events of the specified key only.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param listener entry listener
* @param key the key to listen
* @param includeValue true if EntryEvent should
* contain the value.
* @return returns registration id.
*/
String addEntryListener(EntryListener listener, K key, boolean includeValue);
/**
* 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.
*
* Scope of the lock is this multimap only.
* 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key key to lock.
*/
void lock(K key);
/**
* Acquires the lock for the specified key for the specified lease time.
* After lease time, 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
* @param key key to lock.
* @param leaseTime time to wait before releasing the lock.
* @param timeUnit unit of time to specify lease time.
*/
void lock(K key, long leaseTime, TimeUnit timeUnit);
/**
* Checks the lock for the specified key.
* If the lock is acquired then returns true, else false.
*
* Warning:
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
* @param key key to lock to be checked.
* @return true if lock is acquired, 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
* doesn't wait and returns false immediately.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key key to lock.
* @return true if lock is acquired, 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param time the maximum time to wait for the lock
* @param timeunit the time unit of the time argument.
* @return true if the lock was acquired and false
* if the waiting time elapsed before the lock was acquired.
*/
boolean tryLock(K key, long time, TimeUnit timeunit)
throws InterruptedException;
/**
* Releases the lock for the specified key. It never blocks and
* returns immediately.
*
* Warning:
*
* This method uses hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
*
* @param key 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 hashCode and equals of binary form of
* the key, not the actual implementations of hashCode and equals
* defined in key's class.
*
* @param key key to lock.
*/
void forceUnlock(K key);
/**
* Returns LocalMultiMapStats for this map.
* LocalMultiMapStats is the statistics for the local portion of this
* distributed multi map and contains information such as ownedEntryCount
* backupEntryCount, lastUpdateTime, 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 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}.
*
* @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
*/
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}.
*
* @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
*/
Result aggregate(Supplier supplier,
Aggregation aggregation,
JobTracker jobTracker);
}