PageRenderTime 20ms CodeModel.GetById 3ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 0ms

/hazelcast/src/main/java/com/hazelcast/core/IMap.java

https://bitbucket.org/gabral6_gmailcom/hazelcast
Java | 900 lines | 62 code | 55 blank | 783 comment | 0 complexity | 887998ab5e8382844a1f06d624561eb4 MD5 | raw file
  1/*
  2 * Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 * http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 */
 16
 17package com.hazelcast.core;
 18
 19import com.hazelcast.monitor.LocalMapStats;
 20import com.hazelcast.query.Expression;
 21import com.hazelcast.query.Predicate;
 22
 23import java.util.Collection;
 24import java.util.Map;
 25import java.util.Set;
 26import java.util.concurrent.ConcurrentMap;
 27import java.util.concurrent.Future;
 28import java.util.concurrent.TimeUnit;
 29import java.util.concurrent.TimeoutException;
 30
 31/**
 32 * Concurrent, distributed, observable and queryable map.
 33 * <p/>
 34 * <p><b>This class is <i>not</i> a general-purpose <tt>ConcurrentMap</tt> implementation! While this class implements
 35 * the <tt>Map</tt> interface, it intentionally violates <tt>Map's</tt> general contract, which mandates the
 36 * use of the <tt>equals</tt> method when comparing objects. Instead of the <tt>equals</tt> method this implementation
 37 * compares the serialized byte version of the objects.</b>
 38 * <p/>
 39 * <p>
 40 * <b>Gotchas:</b>
 41 * <ul>
 42 * <li>
 43 * Methods, including but not limited to <tt>get</tt>, <tt>containsKey</tt>,
 44 * <tt>containsValue</tt>, <tt>evict</tt>, <tt>remove</tt>, <tt>put</tt>,
 45 * <tt>putIfAbsent</tt>, <tt>replace</tt>, <tt>lock</tt>,
 46 * <tt>unlock</tt>, do not use <tt>hashCode</tt> and <tt>equals</tt> implementations of keys,
 47 * instead they use <tt>hashCode</tt> and <tt>equals</tt> of binary (serialized) forms of the objects.
 48 * </li>
 49 * <li>
 50 * <tt>get</tt> method returns a clone of original values, modifying the returned value does not change
 51 * the actual value in the map. One should put modified value back to make changes visible to all nodes.
 52 * For additional info see {@link IMap#get(Object)}.
 53 * </li>
 54 * </li>
 55 * <li>
 56 * Methods, including but not limited to <tt>keySet</tt>, <tt>values</tt>, <tt>entrySet</tt>,
 57 * return a collection clone of the values. The collection is <b>NOT</b> backed by the map,
 58 * so changes to the map are <b>NOT</b> reflected in the collection, and vice-versa.
 59 * </li>
 60 * </ul>
 61 * </p>
 62 *
 63 * @param <K> key
 64 * @param <V> value
 65 * @see java.util.concurrent.ConcurrentMap
 66 * @see java.util.IdentityHashMap
 67 */
 68public interface IMap<K, V> extends ConcurrentMap<K, V>, Instance {
 69
 70    /**
 71     * {@inheritDoc}
 72     * <p/>
 73     * <p><b>Warning:</b></p>
 74     * <p>
 75     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
 76     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
 77     * defined in <tt>key</tt>'s class.
 78     * </p>
 79     */
 80    boolean containsKey(Object key);
 81
 82    /**
 83     * {@inheritDoc}
 84     */
 85    boolean containsValue(Object value);
 86
 87    /**
 88     * {@inheritDoc}
 89     * <p/>
 90     * <p><b>Warning:</b></p>
 91     * <p>
 92     * This method returns a clone of original value, modifying the returned value does not change
 93     * the actual value in the map. One should put modified value back to make changes visible to all nodes.
 94     * <pre>
 95     *      V value = map.get(key);
 96     *      value.updateSomeProperty();
 97     *      map.put(key, value);
 98     * </pre>
 99     * </p>
100     * <p/>
101     * <p><b>Warning-2:</b></p>
102     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
103     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
104     * defined in <tt>key</tt>'s class.
105     * <p/>
106     * <p><b>Warning-3:</b></p>
107     * <p>
108     * If <tt>cache-value</tt> is true (default is true), this method returns a clone of original value
109     * but also caches that value for fast access in local. Modifications done to this cached value without
110     * putting it back to map will be visible to only local node, not entire cluster,
111     * successive <tt>get</tt> calls will return the same cached value.
112     * To reflect modifications to distributed map, one should put modified value back into map.
113     * </p>
114     */
115    V get(Object key);
116
117    /**
118     * {@inheritDoc}
119     * <p/>
120     * <p><b>Warning:</b></p>
121     * <p>
122     * This method returns a clone of previous value, not the original (identically equal) value
123     * previously put into map.
124     * </p>
125     * <p/>
126     * <p><b>Warning-2:</b></p>
127     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
128     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
129     * defined in <tt>key</tt>'s class.
130     */
131    V put(K key, V value);
132
133    /**
134     * {@inheritDoc}
135     * <p/>
136     * <p><b>Warning:</b></p>
137     * <p>
138     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
139     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
140     * defined in <tt>key</tt>'s class.
141     * </p>
142     * <p/>
143     * <p><b>Warning-2:</b></p>
144     * <p>
145     * This method returns a clone of previous value, not the original (identically equal) value
146     * previously put into map.
147     * </p>
148     */
149    V remove(Object key);
150
151    /**
152     * {@inheritDoc}
153     * <p/>
154     * <p><b>Warning:</b></p>
155     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
156     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
157     * defined in <tt>key</tt>'s class.
158     */
159    boolean remove(Object key, Object value);
160
161    /**
162     * If this map has a MapStore and write-delay-seconds is
163     * bigger than 0 (write-behind) then this method flushes
164     * all the local dirty entries by calling MapStore.storeAll() and/or MapStore.deleteAll()
165     */
166    void flush();
167
168    /**
169     * Returns the name of this map
170     *
171     * @return name of this map
172     */
173    String getName();
174
175    /**
176     * Returns the entries for the given keys.
177     * <p/>
178     * <p><b>Warning:</b></p>
179     * The returned map is <b>NOT</b> backed by the original map,
180     * so changes to the original map are <b>NOT</b> reflected in the returned map, and vice-versa.
181     * <p/>
182     * <p><b>Warning-2:</b></p>
183     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
184     * the <tt>keys</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
185     * defined in <tt>key</tt>'s class.
186     *
187     * @param keys keys to get
188     * @return map of entries
189     */
190    Map<K, V> getAll(Set<K> keys);
191
192    /**
193     * Asynchronously gets the given key.
194     * <code>
195     * Future future = map.getAsync(key);
196     * // do some other stuff, when ready get the result
197     * Object value = future.get();
198     * </code>
199     * Future.get() will block until the actual map.get() completes.
200     * If the application requires timely response,
201     * then Future.get(timeout, timeunit) can be used.
202     * <code>
203     * try{
204     * Future future = map.getAsync(key);
205     * Object value = future.get(40, TimeUnit.MILLISECOND);
206     * }catch (TimeoutException t) {
207     * // time wasn't enough
208     * }
209     * </code>
210     * ExecutionException is never thrown.
211     * <p/>
212     * <p><b>Warning:</b></p>
213     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
214     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
215     * defined in <tt>key</tt>'s class.
216     *
217     * @param key the key of the map entry
218     * @return Future from which the value of the key can be retrieved.
219     * @see java.util.concurrent.Future
220     */
221    Future<V> getAsync(K key);
222
223    /**
224     * Asynchronously puts the given key and value.
225     * <code>
226     * Future future = map.putAsync(key, value);
227     * // do some other stuff, when ready get the result
228     * Object oldValue = future.get();
229     * </code>
230     * Future.get() will block until the actual map.get() completes.
231     * If the application requires timely response,
232     * then Future.get(timeout, timeunit) can be used.
233     * <code>
234     * try{
235     * Future future = map.putAsync(key, newValue);
236     * Object oldValue = future.get(40, TimeUnit.MILLISECOND);
237     * }catch (TimeoutException t) {
238     * // time wasn't enough
239     * }
240     * </code>
241     * ExecutionException is never thrown.
242     * <p/>
243     * <p><b>Warning:</b></p>
244     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
245     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
246     * defined in <tt>key</tt>'s class.
247     *
248     * @param key   the key of the map entry
249     * @param value the new value of the map entry
250     * @return Future from which the old value of the key can be retrieved.
251     * @see java.util.concurrent.Future
252     */
253    Future<V> putAsync(K key, V value);
254
255    /**
256     * Asynchronously removes the given key.
257     * <p/>
258     * <p><b>Warning:</b></p>
259     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
260     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
261     * defined in <tt>key</tt>'s class.
262     *
263     * @param key The key of the map entry to remove.
264     * @return A {@link java.util.concurrent.Future} from which the value
265     *         removed from the map can be retrieved.
266     */
267    Future<V> removeAsync(K key);
268
269    /**
270     * Tries to remove the entry with the given key from this map
271     * within specified timeout value. If the key is already locked by another
272     * thread and/or member, then this operation will wait timeout
273     * amount for acquiring the lock.
274     * <p/>
275     * <p><b>Warning:</b></p>
276     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
277     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
278     * defined in <tt>key</tt>'s class.
279     * <p/>
280     * <p><b>Warning-2:</b></p>
281     * <p>
282     * This method returns a clone of previous value, not the original (identically equal) value
283     * previously put into map.
284     * </p>
285     *
286     * @param key      key of the entry
287     * @param timeout  maximum time to wait for acquiring the lock
288     *                 for the key
289     * @param timeunit time unit for the timeout
290     * @return removed value of the entry
291     * @throws java.util.concurrent.TimeoutException
292     *          if lock cannot be acquired for the given key within timeout
293     */
294    Object tryRemove(K key, long timeout, TimeUnit timeunit) throws TimeoutException;
295
296    /**
297     * Tries to put the given key, value into this map within specified
298     * timeout value. If this method returns false, it means that
299     * the caller thread couldn't acquire the lock for the key within
300     * timeout duration, thus put operation is not successful.
301     * <p/>
302     * <p><b>Warning:</b></p>
303     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
304     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
305     * defined in <tt>key</tt>'s class.
306     *
307     * @param key      key of the entry
308     * @param value    value of the entry
309     * @param timeout  maximum time to wait
310     * @param timeunit time unit for the timeout
311     * @return <tt>true</tt> if the put is successful, <tt>false</tt>
312     *         otherwise.
313     */
314    boolean tryPut(K key, V value, long timeout, TimeUnit timeunit);
315
316    /**
317     * Puts an entry into this map with a given ttl (time to live) value.
318     * Entry will expire and get evicted after the ttl. If ttl is 0, then
319     * the entry lives forever.
320     * <p/>
321     * <p><b>Warning:</b></p>
322     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
323     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
324     * defined in <tt>key</tt>'s class.
325     * <p/>
326     * <p><b>Warning-2:</b></p>
327     * <p>
328     * This method returns a clone of previous value, not the original (identically equal) value
329     * previously put into map.
330     * </p>
331     *
332     * @param key      key of the entry
333     * @param value    value of the entry
334     * @param ttl      maximum time for this entry to stay in the map
335     *                 0 means infinite.
336     * @param timeunit time unit for the ttl
337     * @return old value of the entry
338     */
339    V put(K key, V value, long ttl, TimeUnit timeunit);
340
341    /**
342     * Same as {@link #put(K, V, long, TimeUnit)} but MapStore, if defined,
343     * will not be called to store/persist the entry.  If ttl is 0, then
344     * the entry lives forever.
345     * <p/>
346     * <p><b>Warning:</b></p>
347     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
348     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
349     * defined in <tt>key</tt>'s class.
350     *
351     * @param key      key of the entry
352     * @param value    value of the entry
353     * @param ttl      maximum time for this entry to stay in the map.
354     *                 0 means infinite.
355     * @param timeunit time unit for the ttl
356     */
357    void putTransient(K key, V value, long ttl, TimeUnit timeunit);
358
359    /**
360     * {@inheritDoc}
361     * <p/>
362     * <p><b>Warning:</b></p>
363     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
364     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
365     * defined in <tt>key</tt>'s class.
366     * <p/>
367     * <p><b>Warning-2:</b></p>
368     * <p>
369     * This method returns a clone of previous value, not the original (identically equal) value
370     * previously put into map.
371     * </p>
372     */
373    V putIfAbsent(K key, V value);
374
375    /**
376     * Puts an entry into this map with a given ttl (time to live) value
377     * if the specified key is not already associated with a value.
378     * Entry will expire and get evicted after the ttl.
379     * <p/>
380     * <p><b>Warning:</b></p>
381     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
382     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
383     * defined in <tt>key</tt>'s class.
384     * <p/>
385     * <p><b>Warning-2:</b></p>
386     * <p>
387     * This method returns a clone of previous value, not the original (identically equal) value
388     * previously put into map.
389     * </p>
390     *
391     * @param key      key of the entry
392     * @param value    value of the entry
393     * @param ttl      maximum time for this entry to stay in the map
394     * @param timeunit time unit for the ttl
395     * @return old value of the entry
396     */
397    V putIfAbsent(K key, V value, long ttl, TimeUnit timeunit);
398
399    /**
400     * {@inheritDoc}
401     * <p/>
402     * <p><b>Warning:</b></p>
403     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
404     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
405     * defined in <tt>key</tt>'s class.
406     */
407    boolean replace(K key, V oldValue, V newValue);
408
409    /**
410     * {@inheritDoc}
411     * <p/>
412     * <p><b>Warning:</b></p>
413     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
414     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
415     * defined in <tt>key</tt>'s class.
416     * <p/>
417     * <p><b>Warning-2:</b></p>
418     * <p>
419     * This method returns a clone of previous value, not the original (identically equal) value
420     * previously put into map.
421     * </p>
422     */
423    V replace(K key, V value);
424
425    /**
426     * Puts an entry into this map with a given ttl (time to live) value.
427     * Entry will expire and get evicted after the ttl. If ttl is 0, then
428     * the entry lives forever. Similar to put operation except that set
429     * doesn't return the old value which is more efficient.
430     * <p/>
431     * <p><b>Warning:</b></p>
432     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
433     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
434     * defined in <tt>key</tt>'s class.
435     *
436     * @param key      key of the entry
437     * @param value    value of the entry
438     * @param ttl      maximum time for this entry to stay in the map
439     *                 0 means infinite.
440     * @param timeunit time unit for the ttl
441     * @return old value of the entry
442     */
443    void set(K key, V value, long ttl, TimeUnit timeunit);
444
445    /**
446     * Tries to acquire the lock for the specified key and returns
447     * the value of the key if lock is required in time.
448     * <p>If the lock is not available then
449     * the current thread becomes disabled for thread scheduling
450     * purposes and lies dormant until one of two things happens:
451     * <ul>
452     * <li>The lock is acquired by the current thread; or
453     * <li>The specified waiting time elapses
454     * </ul>
455     * <p/>
456     * <p><b>Warning:</b></p>
457     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
458     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
459     * defined in <tt>key</tt>'s class.
460     * <p/>
461     * <p><b>Warning:</b></p>
462     * <p>
463     * This method returns a clone of original value, modifying the returned value does not change
464     * the actual value in the map. One should put modified value back to make changes visible to all nodes.
465     * <pre>
466     *      V value = map.get(key);
467     *      value.updateSomeProperty();
468     *      map.put(key, value);
469     * </pre>
470     * </p>
471     *
472     * @param key      key of the entry
473     * @param time     maximum time to wait for the lock
474     * @param timeunit time unit of the <tt>time</tt> argument.
475     * @return value of the key in this map
476     * @throws java.util.concurrent.TimeoutException
477     *          if lock cannot be acquired in time.
478     */
479    V tryLockAndGet(K key, long time, TimeUnit timeunit) throws TimeoutException;
480
481    /**
482     * Puts the key and value into this map and unlocks the key
483     * if the calling thread owns the lock.
484     * <p/>
485     * <p><b>Warning:</b></p>
486     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
487     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
488     * defined in <tt>key</tt>'s class.
489     *
490     * @param key   key of the entry
491     * @param value value of the entry
492     */
493    void putAndUnlock(K key, V value);
494
495    /**
496     * Acquires the lock for the specified key.
497     * <p>If the lock is not available then
498     * the current thread becomes disabled for thread scheduling
499     * purposes and lies dormant until the lock has been acquired.
500     * <p/>
501     * Scope of the lock is this map only.
502     * Acquired lock is only for the key in this map.
503     * <p/>
504     * Locks are re-entrant so if the key is locked N times then
505     * it should be unlocked N times before another thread can acquire it.
506     * <p/>
507     * <p><b>Warning:</b></p>
508     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
509     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
510     * defined in <tt>key</tt>'s class.
511     *
512     * @param key key to lock.
513     */
514    void lock(K key);
515
516    /**
517     * Checks the lock for the specified key.
518     * <p>If the lock is acquired then returns true, else false.
519     * <p/>
520     * <p><b>Warning:</b></p>
521     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
522     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
523     * defined in <tt>key</tt>'s class.
524     *
525     * @param key key to lock to be checked.
526     * @return <tt>true</tt> if lock is acquired, <tt>false</tt> otherwise.
527     */
528    boolean isLocked(K key);
529
530    /**
531     * Tries to acquire the lock for the specified key.
532     * <p>If the lock is not available then the current thread
533     * doesn't wait and returns false immediately.
534     * <p/>
535     * <p><b>Warning:</b></p>
536     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
537     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
538     * defined in <tt>key</tt>'s class.
539     *
540     * @param key key to lock.
541     * @return <tt>true</tt> if lock is acquired, <tt>false</tt> otherwise.
542     */
543    boolean tryLock(K key);
544
545    /**
546     * Tries to acquire the lock for the specified key.
547     * <p>If the lock is not available then
548     * the current thread becomes disabled for thread scheduling
549     * purposes and lies dormant until one of two things happens:
550     * <ul>
551     * <li>The lock is acquired by the current thread; or
552     * <li>The specified waiting time elapses
553     * </ul>
554     * <p/>
555     * <p><b>Warning:</b></p>
556     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
557     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
558     * defined in <tt>key</tt>'s class.
559     *
560     * @param key      key to lock in this map
561     * @param time     maximum time to wait for the lock
562     * @param timeunit time unit of the <tt>time</tt> argument.
563     * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
564     *         if the waiting time elapsed before the lock was acquired.
565     */
566    boolean tryLock(K key, long time, TimeUnit timeunit);
567
568    /**
569     * Releases the lock for the specified key. It never blocks and
570     * returns immediately.
571     *
572     * <p>If the current thread is the holder of this lock then the hold
573     * count is decremented.  If the hold count is now zero then the lock
574     * is released.  If the current thread is not the holder of this
575     * lock then {@link IllegalMonitorStateException} is thrown.
576     *
577     * <p/>
578     * <p><b>Warning:</b></p>
579     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
580     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
581     * defined in <tt>key</tt>'s class.
582     *
583     * @param key key to lock.
584     * @throws IllegalMonitorStateException if the current thread does not hold this lock
585     */
586    void unlock(K key);
587
588    /**
589     * Releases the lock for the specified key regardless of the lock owner.
590     * It always successfully unlocks the key, never blocks
591     * and returns immediately.
592     * <p/>
593     * <p><b>Warning:</b></p>
594     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
595     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
596     * defined in <tt>key</tt>'s class.
597     *
598     * @param key key to lock.
599     */
600    void forceUnlock(K key);
601
602    /**
603     * Tries to acquire the lock for the entire map.
604     * The thread that locks the map can do all the operations
605     * but other threads in the cluster cannot operate on the map.
606     * <p>If the lock is not available then
607     * the current thread becomes disabled for thread scheduling
608     * purposes and lies dormant until one of two things happens:
609     * <ul>
610     * <li>The lock is acquired by the current thread; or
611     * <li>The specified waiting time elapses
612     * </ul>
613     *
614     * @param time     maximum time to wait for the lock
615     * @param timeunit time unit of the <tt>time</tt> argument.
616     * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
617     *         if the waiting time elapsed before the lock was acquired.
618     */
619    boolean lockMap(long time, TimeUnit timeunit);
620
621    /**
622     * Unlocks the map. It never blocks and
623     * returns immediately.
624     */
625    void unlockMap();
626
627    /**
628     * Adds a local entry listener for this map. Added listener will be only
629     * listening for the events (add/remove/update/evict) of the locally owned entries.
630     * <p/>
631     * Note that entries in distributed map are partitioned across
632     * the cluster members; each member owns and manages the some portion of the
633     * entries. Owned entries are called local entries. This
634     * listener will be listening for the events of local entries. Let's say
635     * your cluster has member1 and member2. On member2 you added a local listener and from
636     * member1, you call <code>map.put(key2, value2)</code>.
637     * If the key2 is owned by member2 then the local listener will be
638     * notified for the add/update event. Also note that entries can migrate to
639     * other nodes for load balancing and/or membership change.
640     *
641     * @param listener entry listener
642     * @see #localKeySet()
643     */
644    void addLocalEntryListener(EntryListener<K, V> listener);
645
646    /**
647     * Adds an entry listener for this map. Listener will get notified
648     * for all map add/remove/update/evict events.
649     *
650     * @param listener     entry listener
651     * @param includeValue <tt>true</tt> if <tt>EntryEvent</tt> should
652     *                     contain the value.
653     */
654    void addEntryListener(EntryListener<K, V> listener, boolean includeValue);
655
656    /**
657     * Removes the specified entry listener
658     * Returns silently if there is no such listener added before.
659     *
660     * @param listener entry listener
661     */
662    void removeEntryListener(EntryListener<K, V> listener);
663
664    /**
665     * Adds the specified entry listener for the specified key.
666     * The listener will get notified for all
667     * add/remove/update/evict events of the specified key only.
668     * <p/>
669     * <p><b>Warning:</b></p>
670     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
671     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
672     * defined in <tt>key</tt>'s class.
673     *
674     * @param listener     entry listener
675     * @param key          key to listen
676     * @param includeValue <tt>true</tt> if <tt>EntryEvent</tt> should
677     *                     contain the value.
678     */
679    void addEntryListener(EntryListener<K, V> listener, K key, boolean includeValue);
680
681    /**
682     * Removes the specified entry listener for the specified key.
683     * Returns silently if there is no such listener added before for
684     * the key.
685     * <p/>
686     * <p><b>Warning:</b></p>
687     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
688     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
689     * defined in <tt>key</tt>'s class.
690     *
691     * @param listener
692     * @param key
693     */
694    void removeEntryListener(EntryListener<K, V> listener, K key);
695
696    /**
697     * Returns the <tt>MapEntry</tt> for the specified key.
698     * <p/>
699     * <p><b>Warning:</b></p>
700     * <p>
701     * This method returns a clone of original mapping, modifying the returned value does not change
702     * the actual value in the map. One should put modified value back to make changes visible to all nodes.
703     * </p>
704     * <p/>
705     * <p><b>Warning-2:</b></p>
706     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
707     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
708     * defined in <tt>key</tt>'s class.
709     *
710     * @param key key of the entry
711     * @return <tt>MapEntry</tt> of the specified key
712     * @see MapEntry
713     */
714    MapEntry<K, V> getMapEntry(K key);
715
716    /**
717     * Evicts the specified key from this map. If
718     * a <tt>MapStore</tt> defined for this map, then the entry is not
719     * deleted from the underlying <tt>MapStore</tt>, evict only removes
720     * the entry from the memory.
721     * <p/>
722     * <p><b>Warning:</b></p>
723     * This method uses <tt>hashCode</tt> and <tt>equals</tt> of binary form of
724     * the <tt>key</tt>, not the actual implementations of <tt>hashCode</tt> and <tt>equals</tt>
725     * defined in <tt>key</tt>'s class.
726     *
727     * @param key key to evict
728     * @return <tt>true</tt> if the key is evicted, <tt>false</tt> otherwise.
729     */
730    boolean evict(Object key);
731
732    /**
733     * Returns a set clone of the keys contained in this map.
734     * The set is <b>NOT</b> backed by the map,
735     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
736     *
737     * @return a set clone of the keys contained in this map
738     */
739    Set<K> keySet();
740
741    /**
742     * Returns a collection clone of the values contained in this map.
743     * The collection is <b>NOT</b> backed by the map,
744     * so changes to the map are <b>NOT</b> reflected in the collection, and vice-versa.
745     *
746     * @return a collection clone of the values contained in this map
747     */
748    Collection<V> values();
749
750    /**
751     * Returns a {@link Set} clone of the mappings contained in this map.
752     * The set is <b>NOT</b> backed by the map,
753     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
754     *
755     * @return a set clone of the keys mappings in this map
756     */
757    Set<Map.Entry<K, V>> entrySet();
758
759    /**
760     * Queries the map based on the specified predicate and
761     * returns the keys of matching entries.
762     * <p/>
763     * Specified predicate runs on all members in parallel.
764     * <p/>
765     * <p><b>Warning:</b></p>
766     * The set is <b>NOT</b> backed by the map,
767     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
768     *
769     * @param predicate query criteria
770     * @return result key set of the query
771     */
772    Set<K> keySet(Predicate predicate);
773
774    /**
775     * Queries the map based on the specified predicate and
776     * returns the matching entries.
777     * <p/>
778     * Specified predicate runs on all members in parallel.
779     * <p/>
780     * <p><b>Warning:</b></p>
781     * The set is <b>NOT</b> backed by the map,
782     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
783     *
784     * @param predicate query criteria
785     * @return result entry set of the query
786     */
787
788    Set<Map.Entry<K, V>> entrySet(Predicate predicate);
789
790    /**
791     * Queries the map based on the specified predicate and
792     * returns the values of matching entries.
793     * <p/>
794     * Specified predicate runs on all members in parallel.
795     * <p/>
796     * <p><b>Warning:</b></p>
797     * The collection is <b>NOT</b> backed by the map,
798     * so changes to the map are <b>NOT</b> reflected in the collection, and vice-versa.
799     *
800     * @param predicate query criteria
801     * @return result value collection of the query
802     */
803
804    Collection<V> values(Predicate predicate);
805
806    /**
807     * Returns the locally owned set of keys.
808     * <p/>
809     * Each key in this map is owned and managed by a specific
810     * member in the cluster.
811     * <p/>
812     * Note that ownership of these keys might change over time
813     * so that key ownerships can be almost evenly distributed
814     * in the cluster.
815     * <p/>
816     * <p><b>Warning:</b></p>
817     * The set is <b>NOT</b> backed by the map,
818     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
819     *
820     * @return locally owned keys.
821     */
822    Set<K> localKeySet();
823
824    /**
825     * Returns the keys of matching locally owned entries.
826     * <p/>
827     * Each key in this map is owned and managed by a specific
828     * member in the cluster.
829     * <p/>
830     * Note that ownership of these keys might change over time
831     * so that key ownerships can be almost evenly distributed
832     * in the cluster.
833     * <p/>
834     * <p><b>Warning:</b></p>
835     * The set is <b>NOT</b> backed by the map,
836     * so changes to the map are <b>NOT</b> reflected in the set, and vice-versa.
837     *
838     * @param predicate query criteria
839     * @return keys of matching locally owned entries.
840     */
841    Set<K> localKeySet(Predicate predicate);
842
843    /**
844     * Adds an index to this map for the specified entries so
845     * that queries can run faster.
846     * <p/>
847     * Let's say your map values are Employee objects.
848     * <pre>
849     *   public class Employee implements Serializable {
850     *       private boolean active = false;
851     *       private int age;
852     *       private String name = null;
853     *       // other fields.
854     *
855     *       // getters setter
856     *
857     *   }
858     * </pre>
859     * <p/>
860     * If you are querying your values mostly based on age and active then
861     * you should consider indexing these fields.
862     * <pre>
863     *   IMap imap = Hazelcast.getMap("employees");
864     *   imap.addIndex("age", true);        // ordered, since we have ranged queries for this field
865     *   imap.addIndex("active", false);    // not ordered, because boolean field cannot have range
866     * </pre>
867     * <p/>
868     * Index attribute should either have a getter method or be public.
869     * You should also make sure to add the indexes before adding
870     * entries to this map.
871     *
872     * @param attribute attribute of value
873     * @param ordered   <tt>true</tt> if index should be ordered,
874     *                  <tt>false</tt> otherwise.
875     */
876    void addIndex(String attribute, boolean ordered);
877
878    /**
879     * Adds an index to this map based on the provided expression.
880     *
881     * @param expression expression for the index.
882     * @param ordered    <tt>true</tt> if index should be ordered,
883     *                   <tt>false</tt> otherwise.
884     */
885    void addIndex(Expression<?> expression, boolean ordered);
886
887    /**
888     * Returns LocalMapStats for this map.
889     * LocalMapStats is the statistics for the local portion of this
890     * distributed map and contains information such as ownedEntryCount
891     * backupEntryCount, lastUpdateTime, lockedEntryCount.
892     * <p/>
893     * Since this stats are only for the local portion of this map, if you
894     * need the cluster-wide MapStats then you need to get the LocalMapStats
895     * from all members of the cluster and combine them.
896     *
897     * @return this map's local statistics.
898     */
899    LocalMapStats getLocalMapStats();
900}