/hazelcast/src/main/java/com/hazelcast/core/IMap.java
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}