com.hazelcast.core.IMap Maven / Gradle / Ivy
/*
* Copyright (c) 2008-2015, 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.map.EntryProcessor;
import com.hazelcast.map.MapInterceptor;
import com.hazelcast.map.QueryResultSizeExceededException;
import com.hazelcast.map.listener.MapListener;
import com.hazelcast.map.listener.MapPartitionLostListener;
import com.hazelcast.mapreduce.JobTracker;
import com.hazelcast.mapreduce.aggregation.Aggregation;
import com.hazelcast.mapreduce.aggregation.Supplier;
import com.hazelcast.monitor.LocalMapStats;
import com.hazelcast.query.Predicate;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
/**
* Concurrent, distributed, observable and queryable map.
*
*
* This class is not a general-purpose ConcurrentMap implementation! While this class implements
* the Map interface, it intentionally violates Map's general contract, which mandates the
* use of the equals method when comparing objects. Instead of the equals method, this implementation
* compares the serialized byte version of the objects.
*
*
* Gotchas:
*
* -
* Methods, including but not limited to get, containsKey,
* containsValue, evict, remove, put,
* putIfAbsent, replace, lock,
* unlock, do not use hashCode and equals implementations of keys.
* Instead, they use hashCode and equals of binary (serialized) forms of the objects.
*
* -
* The 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 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.
*
*
*
* This class does not allow null to be used as a key or value.
*
* @param key
* @param value
* @see java.util.concurrent.ConcurrentMap
*/
public interface IMap extends ConcurrentMap, BaseMap {
/**
* {@inheritDoc}
*
* 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. The key will first be searched for in memory. If the key is not
* found, and if a key is attributed, a {@link MapLoader} will then attempt to load the key.
*
*
* @throws NullPointerException if the specified key is null.
*/
boolean containsKey(Object key);
/**
* {@inheritDoc}
*
* @throws NullPointerException if the specified value is null.
*/
boolean containsValue(Object value);
/**
* {@inheritDoc}
*
* Warning:
*
* 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 hashCode and equals of the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
*
* @throws NullPointerException if the specified key is null.
*/
V get(Object key);
/**
* {@inheritDoc}
*
* Warning:
*
* 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 hashCode and equals of the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @throws NullPointerException if the specified key or value is null.
*/
V put(K key, V value);
/**
* {@inheritDoc}
*
* 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.
*
*
* Warning-2:
*
* This method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* @throws NullPointerException if the specified key is null.
*/
V remove(Object key);
/**
* {@inheritDoc}
*
* 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.
*
* @throws NullPointerException if the specified key or value is null.
*/
boolean remove(Object key, Object value);
/**
* Removes the mapping for a key from this map if it is present
* (optional operation).
*
* Unlike {@link #remove(Object)}, this operation does not return
* the removed value, which avoids the serialization cost of the returned value.
*
* If the removed value will not be used, a delete operation
* is preferred over a 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.
*
*
* @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.
*/
void delete(Object key);
/**
* If this map has a MapStore, this method flushes
* all the local dirty entries by calling MapStore.storeAll() and/or MapStore.deleteAll().
*/
void flush();
/**
* Returns the entries for the given keys. If any keys are not present in the Map, it will
* call {@link MapStore#loadAll(java.util.Collection)}.
*
* Warning:
* The returned map is NOT backed by the original map,
* so changes to the original map are NOT reflected in the returned map, and vice-versa.
*
* Warning-2:
* This method uses hashCode and equals of the binary form of
* the keys, not the actual implementations of hashCode and equals
* defined in the key's class.
*
*
* @param keys keys to get.
* @return map of entries.
* @throws NullPointerException if any of the specified keys are null.
*/
Map getAll(Set keys);
/**
* Loads all keys into the store. This is a batch load operation so that an implementation can
* optimize the multiple loads.
*
* @param replaceExistingValues when true, existing values in the Map will
* be replaced by those loaded from the MapLoader
* void loadAll(boolean replaceExistingValues));
* @since 3.3
*/
void loadAll(boolean replaceExistingValues);
/**
* Loads the given keys. This is a batch load operation so that an implementation can
* optimize the multiple loads.
*
* @param keys keys of the values entries to load.
* @param replaceExistingValues when true, existing values in the Map will
* be replaced by those loaded from the MapLoader.
* @since 3.3
*/
void loadAll(Set keys, boolean replaceExistingValues);
/**
* This method clears the map and invokes {@link MapStore#deleteAll}deleteAll on MapStore which,
* if connected to a database, will delete the records from that database.
*
* The MAP_CLEARED event is fired for any registered listeners.
* See {@link com.hazelcast.core.EntryListener#mapCleared(MapEvent)}.
*
* To clear a map without calling {@link MapStore#deleteAll}, use {@link #evictAll}.
*
* @see #evictAll
*/
@Override
void clear();
/**
* Asynchronously gets the given key.
*
* Future future = map.getAsync(key);
* // do some other stuff, when ready get the result.
* Object value = future.get();
*
* Future.get() will block until the actual map.get() completes.
* If the application requires timely response,
* then Future.get(timeout, timeunit) can be used.
*
* try{
* Future future = map.getAsync(key);
* Object value = future.get(40, TimeUnit.MILLISECOND);
* }catch (TimeoutException t) {
* // time wasn't enough
* }
*
* ExecutionException is never thrown.
*
* 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 key the key of the map entry.
* @return Future from which the value of the key can be retrieved.
* @throws NullPointerException if the specified key is null.
* @see java.util.concurrent.Future
*/
Future getAsync(K key);
/**
* Asynchronously puts the given key and value.
*
* Future future = map.putAsync(key, value);
* // do some other stuff, when ready get the result.
* Object oldValue = future.get();
*
* Future.get() will block until the actual map.put() completes.
* If the application requires a timely response,
* then you can use Future.get(timeout, timeunit).
*
* try{
* Future future = map.putAsync(key, newValue);
* Object oldValue = future.get(40, TimeUnit.MILLISECOND);
* }catch (TimeoutException t) {
* // time wasn't enough
* }
*
* ExecutionException is never thrown.
*
* 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 key the key of the map entry.
* @param value the new value of the map entry.
* @return Future from which the old value of the key can be retrieved.
* @throws NullPointerException if the specified key or value is null.
* @see java.util.concurrent.Future
*/
Future putAsync(K key, V value);
/**
* Asynchronously puts the given key and value into this map with a given ttl (time to live) value.
* Entry will expire and get evicted after the ttl. If ttl is 0, then
* the entry lives forever.
*
* Future future = map.putAsync(key, value, ttl, timeunit);
* // do some other stuff, when ready get the result
* Object oldValue = future.get();
*
* Future.get() will block until the actual map.get() completes.
* If your application requires a timely response,
* then you can use Future.get(timeout, timeunit).
*
* try{
* Future future = map.putAsync(key, newValue, ttl, timeunit);
* Object oldValue = future.get(40, TimeUnit.MILLISECOND);
* }catch (TimeoutException t) {
* // time wasn't enough
* }
*
* ExecutionException is never thrown.
*
* Warning 1:
* 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.
*
* Warning 2:
* Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
*
* @param key the key of the map entry.
* @param value the new value of the map entry.
* @param ttl maximum time for this entry to stay in the map.
* 0 means infinite.
* @param timeunit time unit for the ttl.
* @return Future from which the old value of the key can be retrieved.
* @throws NullPointerException if the specified key or value is null.
* @see java.util.concurrent.Future
*/
Future putAsync(K key, V value, long ttl, TimeUnit timeunit);
/**
* Asynchronously removes the given key.
*
* 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 key The key of the map entry to remove.
* @return A {@link java.util.concurrent.Future} from which the value
* removed from the map can be retrieved.
* @throws NullPointerException if the specified key is null.
*/
Future removeAsync(K key);
/**
* Tries to remove the entry with the given key from this map
* within the specified timeout value. If the key is already locked by another
* thread and/or member, then this operation will wait the timeout
* amount for acquiring the lock.
*
* 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.
*
* Warning-2:
*
* This method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* @param key key of the entry.
* @param timeout maximum time to wait for acquiring the lock
* for the key.
* @param timeunit time unit for the timeout.
* @return true if the remove is successful, false
* otherwise.
* @throws NullPointerException if the specified key is null.
*/
boolean tryRemove(K key, long timeout, TimeUnit timeunit);
/**
* Tries to put the given key and value into this map within a specified
* timeout value. If this method returns false, it means that
* the caller thread could not acquire the lock for the key within the
* timeout duration, thus the put operation is not successful.
*
* 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 key key of the entry.
* @param value value of the entry.
* @param timeout maximum time to wait.
* @param timeunit time unit for the timeout.
* @return true if the put is successful, false otherwise.
* @throws NullPointerException if the specified key or value is null.
*/
boolean tryPut(K key, V value, long timeout, TimeUnit timeunit);
/**
* Puts an entry into this map with a given ttl (time to live) value.
* Entry will expire and get evicted after the ttl. If ttl is 0, then
* the entry lives forever.
*
* 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.
*
* Warning-2:
*
* This method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* Warning 3:
* Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map
* 0 means infinite.
* @param timeunit time unit for the ttl
* @return old value of the entry
* @throws NullPointerException if the specified key or value is null
*/
V put(K key, V value, long ttl, TimeUnit timeunit);
/**
* Same as {@link #put(K, V, long, java.util.concurrent.TimeUnit)} except that MapStore, if defined,
* will not be called to store/persist the entry. If ttl is 0, then
* the entry lives forever.
*
* Warning 1:
* 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.
*
* Warning 2:
* Time resolution for TTL is seconds. The given TTL value is rounded to next closest second value.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map.
* 0 means infinite.
* @param timeunit time unit for the ttl
* @throws NullPointerException if the specified key or value is null
*/
void putTransient(K key, V value, long ttl, TimeUnit timeunit);
/**
* {@inheritDoc}
*
* Note:
* 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.
*
* Also, this method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* @return a clone of the previous value.
* @throws NullPointerException if the specified key or value is null.
*/
V putIfAbsent(K key, V value);
/**
* Puts an entry into this map with a given ttl (time to live) value
* if the specified key is not already associated with a value.
* Entry will expire and get evicted after the ttl.
*
* 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.
*
* Warning-2:
*
* This method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* Warning 3:
* Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
*
* @param key key of the entry.
* @param value value of the entry.
* @param ttl maximum time for this entry to stay in the map.
* @param timeunit time unit for the ttl.
* @return old value of the entry.
* @throws NullPointerException if the specified key or value is null.
*/
V putIfAbsent(K key, V value, long ttl, TimeUnit timeunit);
/**
* {@inheritDoc}
*
* 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.
*
* @throws NullPointerException if any of the specified parameters are null.
*/
boolean replace(K key, V oldValue, V newValue);
/**
* {@inheritDoc}
*
* 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.
*
* Warning-2:
*
* This method returns a clone of the previous value, not the original (identically equal) value
* previously put into the map.
*
*
* @throws NullPointerException if the specified key or value is null.
*/
V replace(K key, V value);
/**
* Puts an entry into this map.
* Similar to the put operation except that set
* doesn't return the old value, which is more efficient.
*
* Warning:
* This method breaks the contract of EntryListener.
* When an entry is updated by set(), it fires an EntryEvent with a null oldValue.
*
* Warning-2:
* 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 key key of the entry.
* @param value value of the entry.
* @throws NullPointerException if the specified key or value is null.
*/
void set(K key, V value);
/**
* Puts an entry into this map with a given ttl (time to live) value.
* Entry will expire and get evicted after the ttl. If ttl is 0, then
* the entry lives forever. Similar to the put operation except that set
* doesn't return the old value, which is more efficient.
*
* Warning 1:
* 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.
*
* Warning 2:
* Time resolution for TTL is seconds. The given TTL value is rounded to the next closest second value.
*
* @param key key of the entry
* @param value value of the entry
* @param ttl maximum time for this entry to stay in the map
* 0 means infinite.
* @param timeunit time unit for the ttl
* @throws NullPointerException if the specified key or value is null
*/
void set(K key, V value, long ttl, TimeUnit timeunit);
/**
* 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.
*
* You get a lock whether the value is present in the map or not. Other
* threads (possibly on other systems) would block on their invoke of
* lock() until the non-existent key is unlocked. If the lock
* holder introduces the key to the map, the put() operation
* is not blocked. If a thread not holding a lock on the non-existent key
* tries to introduce the key while a lock exists on the non-existent key,
* the put() operation blocks until it is unlocked.
*
* 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.
*
* There is no lock timeout on this method. Locks will be held infinitely.
* 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 key key to lock.
* @throws NullPointerException if the specified key is null.
*/
void lock(K key);
/**
* Acquires 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 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 the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @param key the key to lock.
* @param leaseTime time to wait before releasing the lock.
* @param timeUnit unit of time to specify lease time.
* @throws NullPointerException if the specified key is null.
*/
void lock(K key, long leaseTime, TimeUnit timeUnit);
/**
* Checks the lock for the specified key.
* If the lock is acquired then returns true, else returns false.
*
* 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 key the key that is checked for lock.
* @return true if lock is acquired, false otherwise.
* @throws NullPointerException if the specified key is null.
*/
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 the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @param key the key to lock.
* @return true if lock is acquired, false otherwise.
* @throws NullPointerException if the specified key is null.
*/
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 the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the 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 time argument.
* @return true if the lock was acquired and false
* if the waiting time elapsed before the lock was acquired.
* @throws NullPointerException if the specified key is null.
*/
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 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 key key to lock in this map.
* @param time maximum time to wait for the lock.
* @param timeunit time unit of the time argument.
* @param leaseTime time to wait before releasing the lock.
* @param leaseTimeunit unit of time to specify lease time.
* @return true if the lock was acquired and false
* if the waiting time elapsed before the lock was acquired.
* @throws NullPointerException if the specified key is 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.
*
* If the current thread is the holder of this lock, then the hold
* count is decremented. If the hold count is zero, then the lock
* is released. If the current thread is not the holder of this
* lock, then {@link IllegalMonitorStateException} is thrown.
*
* 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 key the key to lock.
* @throws NullPointerException if the specified key is null.
* @throws IllegalMonitorStateException if the current thread does not hold this 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 the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @param key the key to lock.
* @throws NullPointerException if the specified key is null.
*/
void forceUnlock(K key);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* Note that entries in distributed map 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 map.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 {@link MapListener} for this map.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see #localKeySet()
* @see MapListener
*/
String addLocalEntryListener(MapListener listener);
/**
* Adds a local entry listener for this map. The added listener will only be
* listening for the events (add/remove/update/evict) of the locally owned entries.
*
* Note that entries in distributed map 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 map.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 A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see #localKeySet()
* @deprecated use {@link #addLocalEntryListener(MapListener)} instead.
*/
String addLocalEntryListener(EntryListener listener);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
* Listener will get notified for map events filtered by the given predicate.
*
* @param listener {@link MapListener} for this map.
* @param predicate predicate for filtering entries
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see MapListener
*/
String addLocalEntryListener(MapListener listener, Predicate predicate, boolean includeValue);
/**
* Adds a local entry listener for this map. The added listener will only be
* listening for the events (add/remove/update/evict) of the locally owned entries.
* Listener will get notified for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener entry listener
* @param predicate predicate for filtering entries
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @deprecated use {@link #addLocalEntryListener(MapListener, com.hazelcast.query.Predicate, boolean)}
*/
String addLocalEntryListener(EntryListener listener, Predicate predicate, boolean includeValue);
/**
* Adds a local entry listener for this map. The added listener will only be
* listening for the events (add/remove/update/evict) of the locally owned entries.
* Listener will get notified for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener {@link MapListener} for this map.
* @param predicate predicate for filtering entries.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see MapListener
*/
String addLocalEntryListener(MapListener listener, Predicate predicate, K key, boolean includeValue);
/**
* Adds a local entry listener for this map. The added listener will only be
* listening for the events (add/remove/update/evict) of the locally owned entries.
* Listener will get notified for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener entry listener.
* @param predicate predicate for filtering entries.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @deprecated use {@link #addLocalEntryListener(MapListener, com.hazelcast.query.Predicate, boolean)} instead
*/
String addLocalEntryListener(EntryListener listener, Predicate predicate, K key, boolean includeValue);
/**
* Adds an interceptor for this map. Added interceptor will intercept operations
* and execute user defined methods and will cancel operations if user defined method throw exception.
*
*
* @param interceptor map interceptor.
* @return id of registered interceptor.
*/
String addInterceptor(MapInterceptor interceptor);
/**
* Removes the given interceptor for this map so it will not intercept operations anymore.
*
*
* @param id registration id of the map interceptor.
*/
void removeInterceptor(String id);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* @param listener {@link MapListener} for this map.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see MapListener
*/
String addEntryListener(MapListener listener, boolean includeValue);
/**
* Adds an entry listener for this map. Listener will get notified
* for all map add/remove/update/evict events.
*
* @param listener the added entry listener for this map.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @deprecated use {@link #addEntryListener(MapListener, boolean)} instead.
*/
String addEntryListener(EntryListener listener, boolean includeValue);
/**
* Removes the specified entry listener.
* Returns silently if there is no such listener added before.
*
* @param id id of registered listener.
* @return true if registration is removed, false otherwise.
*/
boolean removeEntryListener(String id);
/**
* Adds a MapPartitionLostListener.
*
* The addPartitionLostListener returns a register-id. This id is needed to remove the MapPartitionLostListener using the
* {@link #removePartitionLostListener(String)} method.
*
* There is no check for duplicate registrations, so if you register the listener twice, it will get events twice.
* IMPORTANT: Please @see com.hazelcast.partition.PartitionLostListener for weaknesses.
* IMPORTANT: Listeners registered from HazelcastClient may miss some of the map partition lost events due
* to design limitations.
*
* @param listener the added MapPartitionLostListener.
* @return returns the registration id for the MapPartitionLostListener.
* @throws java.lang.NullPointerException if listener is null.
* @see #removePartitionLostListener(String)
*/
String addPartitionLostListener(MapPartitionLostListener listener);
/**
* Removes the specified map partition lost listener.
* Returns silently if there is no such listener added before.
*
* @param id id of registered listener.
* @return true if registration is removed, false otherwise.
*/
boolean removePartitionLostListener(String id);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* 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 {@link MapListener} for this map.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @throws NullPointerException if the specified key is null.
* @see MapListener
*/
String addEntryListener(MapListener listener, K key, boolean includeValue);
/**
* 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 the binary form of
* the key, not the actual implementations of hashCode and equals
* defined in the key's class.
*
* @param listener specified entry listener.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @throws NullPointerException if the specified key is null.
* @deprecated use {@link #addEntryListener(MapListener, Predicate, Object, boolean)} instead.
*/
String addEntryListener(EntryListener listener, K key, boolean includeValue);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* @param listener the added continuous {@link MapListener} for this map.
* @param predicate predicate for filtering entries.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see MapListener
*/
String addEntryListener(MapListener listener, Predicate predicate, boolean includeValue);
/**
* Adds an continuous entry listener for this map. Listener will get notified
* for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener the added continuous entry listener for this map.
* @param predicate predicate for filtering entries.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @deprecated use {@link #addEntryListener(MapListener, Predicate, boolean)} instead.
*/
String addEntryListener(EntryListener listener, Predicate predicate, boolean includeValue);
/**
* Adds a {@link MapListener} for this map. To receive an event, you should
* implement a corresponding {@link MapListener} sub-interface for that event.
*
* @param listener the continuous {@link MapListener} for this map.
* @param predicate predicate for filtering entries.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @see MapListener
*/
String addEntryListener(MapListener listener, Predicate predicate, K key, boolean includeValue);
/**
* Adds an continuous entry listener for this map. Listener will get notified
* for map add/remove/update/evict events filtered by the given predicate.
*
* @param listener the continuous entry listener for this map.
* @param predicate predicate for filtering entries.
* @param key key to listen for.
* @param includeValue true if EntryEvent should
* contain the value.
* @return A UUID.randomUUID().toString() which is used as a key to remove the listener.
* @deprecated use {@link #addEntryListener(MapListener, Object, boolean)}
*/
String addEntryListener(EntryListener listener, Predicate predicate, K key, boolean includeValue);
/**
* Returns the EntryView for the specified key.
*
* Warning:
*
* This method returns a clone of original mapping, modifying the returned value does not change
* the actual value in the map. One should put modified value back to make changes visible to all nodes.
*
*
* Warning-2:
* 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 key the key of the entry.
* @return EntryView of the specified key.
* @throws NullPointerException if the specified key is null.
* @see EntryView
*/
EntryView getEntryView(K key);
/**
* Evicts the specified key from this map. If
* a MapStore is defined for this map, then the entry is not
* deleted from the underlying MapStore, evict only removes
* the entry from the memory.
*
* 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 key the specified key to evict from this map.
* @return true if the key is evicted, false otherwise.
* @throws NullPointerException if the specified key is null.
*/
boolean evict(K key);
/**
* Evicts all keys from this map except the locked ones.
*
* If a MapStore is defined for this map, deleteAll is not called by this method.
* If you do want to deleteAll to be called use the {@link #clear()} method.
*
* The EVICT_ALL event is fired for any registered listeners.
* See {@link com.hazelcast.core.EntryListener#mapEvicted(MapEvent)} .
*
* @see #clear()
* @since 3.3
*/
void evictAll();
/**
* Returns a set clone of the keys contained in this map.
*
* Warning:
* The set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return a set clone of the keys contained in this map.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set keySet();
/**
* Returns a collection clone of the values contained in this map.
*
* Warning:
* The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return a collection clone of the values contained in this map
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Collection values();
/**
* Returns a {@link Set} clone of the mappings contained in this map.
*
* Warning:
* The set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return a set clone of the keys mappings in this map
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set> entrySet();
/**
* Queries the map based on the specified predicate and
* returns the keys of matching entries.
*
* Specified predicate runs on all members in parallel.
*
* Warning:
* The set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @param predicate specified query criteria.
* @return result key set of the query.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set keySet(Predicate predicate);
/**
* Queries the map based on the specified predicate and
* returns the matching entries.
*
* Specified predicate runs on all members in parallel.
*
* Warning:
* The set is NOT backed by the map,
* so changes to the map are NOT reflected in the set, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @param predicate specified query criteria.
* @return result entry set of the query.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set> entrySet(Predicate predicate);
/**
* Queries the map based on the specified predicate and
* returns the values of matching entries.
*
* Specified predicate runs on all members in parallel.
*
* Warning:
* The collection is NOT backed by the map,
* so changes to the map are NOT reflected in the collection, and vice-versa.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @param predicate specified query criteria.
* @return result value collection of the query.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Collection values(Predicate predicate);
/**
* 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.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @return locally owned keys.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set localKeySet();
/**
* Returns the keys of matching locally owned entries.
*
* 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.
*
* This method is always executed by a distributed query,
* so it may throw a {@link QueryResultSizeExceededException}
* if {@link com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT} is configured.
*
* @param predicate specified query criteria.
* @return keys of matching locally owned entries.
* @throws QueryResultSizeExceededException if query result size limit is exceeded
* @see com.hazelcast.instance.GroupProperty#QUERY_RESULT_SIZE_LIMIT
*/
Set localKeySet(Predicate predicate);
/**
* Adds an index to this map for the specified entries so
* that queries can run faster.
*
* Let's say your map values are Employee objects.
*
* public class Employee implements Serializable {
* private boolean active = false;
* private int age;
* private String name = null;
* // other fields.
*
* // getters setter
*
* }
*
*
* If you are querying your values mostly based on age and active then
* you should consider indexing these fields.
*
* IMap imap = Hazelcast.getMap("employees");
* imap.addIndex("age", true); // ordered, since we have ranged queries for this field
* imap.addIndex("active", false); // not ordered, because boolean field cannot have range
*
*
* Index attribute should either have a getter method or be public.
* You should also make sure to add the indexes before adding
* entries to this map.
*
* Time to Index
* Indexing time is executed in parallel on each partition by operation threads. The Map
* is not blocked during this operation.
*
* The time taken in proportional to the size of the Map and the number Members.
*
* Searches while indexes are being built
* Until the index finishes being created, any searches for the attribute will use a full Map scan,
* thus avoiding using a partially built index and returning incorrect results.
*
* @param attribute index attribute of value
* @param ordered true if index should be ordered,
* false otherwise.
*/
void addIndex(String attribute, boolean ordered);
/**
* Returns LocalMapStats for this map.
* LocalMapStats is the statistics for the local portion of this
* distributed map and contains information such as ownedEntryCount
* backupEntryCount, lastUpdateTime, lockedEntryCount.
*
* Since this stats are only for the local portion of this map, if you
* need the cluster-wide MapStats then you need to get the LocalMapStats
* from all members of the cluster and combine them.
*
* @return this map's local statistics.
*/
LocalMapStats getLocalMapStats();
/**
* Applies the user defined EntryProcessor to the entry mapped by the key.
* Returns the the object which is result of the process() method of EntryProcessor.
*
*
* @return result of entry process.
* @throws NullPointerException if the specified key is null
*/
Object executeOnKey(K key, EntryProcessor entryProcessor);
/**
* Applies the user defined EntryProcessor to the entries mapped by the collection of keys.
* the results mapped by each key in the collection.
*
*
* @return result of entry process.
* @throws NullPointerException if the specified key is null.
*/
Map executeOnKeys(Set keys, EntryProcessor entryProcessor);
/**
* Applies the user defined EntryProcessor to the entry mapped by the key with
* specified ExecutionCallback to listen event status and returns immediately.
*
* @param key key to be processed.
* @param entryProcessor processor to process the key.
* @param callback to listen whether operation is finished or not.
*/
void submitToKey(K key, EntryProcessor entryProcessor, ExecutionCallback callback);
/**
* Applies the user defined EntryProcessor to the entry mapped by the key.
* Returns immediately with a Future representing that task.
*
* EntryProcessor is not cancellable, so calling Future.cancel() method won't cancel the operation of EntryProcessor.
*
* @param key key to be processed
* @param entryProcessor processor to process the key
* @return Future from which the result of the operation can be retrieved.
* @see java.util.concurrent.Future
*/
Future submitToKey(K key, EntryProcessor entryProcessor);
/**
* Applies the user defined EntryProcessor to the all entries in the map.
* Returns the results mapped by each key in the map.
*
*/
Map executeOnEntries(EntryProcessor entryProcessor);
/**
* Applies the user defined EntryProcessor to the entries in the map which satisfies provided predicate.
* Returns the results mapped by each key in the map.
*
*/
Map executeOnEntries(EntryProcessor entryProcessor, Predicate predicate);
/**
* Executes a predefined aggregation on the maps 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 map.
* @param aggregation the aggregation that is being executed against the map.
* @param the final type emitted from the supplier.
* @param the resulting aggregation value type.
* @return the aggregated value.
*/
Result aggregate(Supplier supplier,
Aggregation aggregation);
/**
* Executes a predefined aggregation on the maps 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 map.
* @param aggregation the aggregation that is being executed against the map.
* @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 the aggregated value
*/
Result aggregate(Supplier supplier,
Aggregation aggregation,
JobTracker jobTracker);
}