/hazelcast/src/main/java/com/hazelcast/core/Hazelcast.java
Java | 680 lines | 185 code | 39 blank | 456 comment | 17 complexity | 4f52cf2605f098a00d0a536b903e0523 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.config.Config; 20import com.hazelcast.logging.LoggingService; 21import com.hazelcast.partition.PartitionService; 22 23import java.util.Collection; 24import java.util.Set; 25import java.util.concurrent.ExecutorService; 26import java.util.concurrent.atomic.AtomicReference; 27 28/** 29 * Factory for all of the Hazelcast data and execution components such as 30 * maps, queues, multimaps, topics and executor service. 31 * <p/> 32 * If not started already, Hazelcast member (HazelcastInstance) will start 33 * automatically if any of the functions is called on Hazelcast. 34 */ 35@SuppressWarnings("SynchronizationOnStaticField") 36public final class Hazelcast { 37 @Deprecated 38 private static final AtomicReference<HazelcastInstance> defaultInstance = new AtomicReference<HazelcastInstance>(); 39 @Deprecated 40 private static final Object initLock = new Object(); 41 @Deprecated 42 private static Config defaultConfig = null; 43 44 private Hazelcast() { 45 } 46 47 /** 48 * Initializes the default Hazelcast instance with the specified configuration. 49 * This method should be called before calling any other methods. 50 * 51 * @param config configuration for this Hazelcast instance. 52 * @return the default instance 53 * @throws IllegalStateException if this instance is already initialized 54 * 55 * @deprecated as of version 2.2 56 * @see #newHazelcastInstance(com.hazelcast.config.Config) 57 * @see #getHazelcastInstanceByName(String) 58 * @see #getAllHazelcastInstances() 59 */ 60 @Deprecated 61 public static HazelcastInstance init(Config config) { 62 if (defaultInstance.get() != null) { 63 throw new IllegalStateException("Default Hazelcast instance is already initialized."); 64 } 65 synchronized (initLock) { 66 if (defaultInstance.get() != null) { 67 throw new IllegalStateException("Default Hazelcast instance is already initialized."); 68 } 69 defaultConfig = config; 70 HazelcastInstance defaultInstanceObject = com.hazelcast.impl.FactoryImpl.newHazelcastInstanceProxy(config); 71 defaultInstance.set(defaultInstanceObject); 72 return defaultInstanceObject; 73 } 74 } 75 76 /** 77 * Returns the default Hazelcast instance, starts it with the default 78 * configuration, if not already started. 79 * 80 * @return the default Hazelcast instance 81 * 82 * @deprecated as of version 2.2 83 * @see #newHazelcastInstance(com.hazelcast.config.Config) 84 * @see #getHazelcastInstanceByName(String) 85 * @see #getAllHazelcastInstances() 86 */ 87 @Deprecated 88 public static HazelcastInstance getDefaultInstance() { 89 HazelcastInstance defaultInstanceObject = defaultInstance.get(); 90 if (defaultInstanceObject == null 91 || !defaultInstanceObject.getLifecycleService().isRunning()) { 92 synchronized (initLock) { 93 defaultInstanceObject = defaultInstance.get(); 94 if (defaultInstanceObject == null 95 || !defaultInstanceObject.getLifecycleService().isRunning()) { 96 defaultInstanceObject = com.hazelcast.impl.FactoryImpl.newHazelcastInstanceProxy(defaultConfig); 97 defaultInstance.set(defaultInstanceObject); 98 return defaultInstanceObject; 99 } else { 100 return defaultInstanceObject; 101 } 102 } 103 } else { 104 return defaultInstanceObject; 105 } 106 } 107 108 /** 109 * Returns the distributed queue instance with the specified name. 110 * 111 * @param name name of the distributed queue 112 * @return distributed queue instance with the specified name 113 * 114 * @deprecated as of version 2.2 115 * @see #newHazelcastInstance(com.hazelcast.config.Config) 116 * @see HazelcastInstance#getQueue(String) 117 */ 118 @Deprecated 119 public static <E> IQueue<E> getQueue(String name) { 120 return getDefaultInstance().getQueue(name); 121 } 122 123 /** 124 * Returns the distributed topic instance with the specified name. 125 * 126 * @param name name of the distributed topic 127 * @return distributed topic instance with the specified name 128 * 129 * @deprecated as of version 2.2 130 * @see #newHazelcastInstance(com.hazelcast.config.Config) 131 * @see HazelcastInstance#getTopic(String) 132 */ 133 @Deprecated 134 public static <E> ITopic<E> getTopic(String name) { 135 return getDefaultInstance().getTopic(name); 136 } 137 138 /** 139 * Returns the distributed set instance with the specified name. 140 * 141 * @param name name of the distributed set 142 * @return distributed set instance with the specified name 143 * 144 * @deprecated as of version 2.2 145 * @see #newHazelcastInstance(com.hazelcast.config.Config) 146 * @see HazelcastInstance#getSet(String) 147 */ 148 @Deprecated 149 public static <E> ISet<E> getSet(String name) { 150 return getDefaultInstance().getSet(name); 151 } 152 153 /** 154 * Returns the distributed list instance with the specified name. 155 * 156 * @param name name of the distributed list 157 * @return distributed list instance with the specified name 158 * 159 * @deprecated as of version 2.2 160 * @see #newHazelcastInstance(com.hazelcast.config.Config) 161 * @see HazelcastInstance#getList(String) 162 */ 163 @Deprecated 164 public static <E> IList<E> getList(String name) { 165 return getDefaultInstance().getList(name); 166 } 167 168 /** 169 * Returns the distributed map instance with the specified name. 170 * 171 * @param name name of the distributed map 172 * @return distributed map instance with the specified name 173 * 174 * @deprecated as of version 2.2 175 * @see #newHazelcastInstance(com.hazelcast.config.Config) 176 * @see HazelcastInstance#getMap(String) 177 */ 178 @Deprecated 179 public static <K, V> IMap<K, V> getMap(String name) { 180 return getDefaultInstance().getMap(name); 181 } 182 183 /** 184 * Returns the distributed multimap instance with the specified name. 185 * 186 * @param name name of the distributed multimap 187 * @return distributed multimap instance with the specified name 188 * 189 * @deprecated as of version 2.2 190 * @see #newHazelcastInstance(com.hazelcast.config.Config) 191 * @see HazelcastInstance#getMultiMap(String) 192 */ 193 @Deprecated 194 public static <K, V> MultiMap<K, V> getMultiMap(String name) { 195 return getDefaultInstance().getMultiMap(name); 196 } 197 198 /** 199 * Returns the distributed lock instance for the specified key object. 200 * The specified object is considered to be the key for this lock. 201 * So keys are considered equals cluster-wide as long as 202 * they are serialized to the same byte array such as String, long, 203 * Integer. 204 * <p/> 205 * Locks are fail-safe. If a member holds a lock and some of the 206 * members go down, cluster will keep your locks safe and available. 207 * Moreover, when a member leaves the cluster, all the locks acquired 208 * by this dead member will be removed so that these locks can be 209 * available for live members immediately. 210 * <pre> 211 * Lock lock = Hazelcast.getLock("PROCESS_LOCK"); 212 * lock.lock(); 213 * try { 214 * // process 215 * } finally { 216 * lock.unlock(); 217 * } 218 * </pre> 219 * 220 * @param key key of the lock instance 221 * @return distributed lock instance for the specified key. 222 * 223 * @deprecated as of version 2.2 224 * @see #newHazelcastInstance(com.hazelcast.config.Config) 225 * @see HazelcastInstance#getLock(Object) 226 */ 227 228 @Deprecated 229 public static ILock getLock(Object key) { 230 return getDefaultInstance().getLock(key); 231 } 232 233 /** 234 * Returns the Cluster that this Hazelcast instance is part of. 235 * Cluster interface allows you to add listener for membership 236 * events and learn more about the cluster that this Hazelcast 237 * instance is part of. 238 * 239 * @return cluster that this Hazelcast instance is part of 240 * 241 * @deprecated as of version 2.2 242 * @see #newHazelcastInstance(com.hazelcast.config.Config) 243 * @see HazelcastInstance#getCluster() 244 */ 245 @Deprecated 246 public static Cluster getCluster() { 247 return getDefaultInstance().getCluster(); 248 } 249 250 /** 251 * Returns the default distributed executor service. Executor 252 * service enables you to run your <tt>Runnable</tt>s and <tt>Callable</tt>s 253 * on the Hazelcast cluster. 254 * 255 * Note that it don't support invokeAll/Any and don't have standard shutdown behavior 256 * 257 * @return distributed executor service of this Hazelcast instance 258 * 259 * @deprecated as of version 2.2 260 * @see #newHazelcastInstance(com.hazelcast.config.Config) 261 * @see HazelcastInstance#getExecutorService() 262 */ 263 @Deprecated 264 public static ExecutorService getExecutorService() { 265 return getDefaultInstance().getExecutorService(); 266 } 267 268 /** 269 * Returns the distributed executor service for the given 270 * name. 271 * 272 * @param name name of the executor service 273 * @return executor service for the given name 274 * 275 * @deprecated as of version 2.2 276 * @see #newHazelcastInstance(com.hazelcast.config.Config) 277 * @see HazelcastInstance#getExecutorService(String) 278 */ 279 @Deprecated 280 public static ExecutorService getExecutorService(String name) { 281 return getDefaultInstance().getExecutorService(name); 282 } 283 284 /** 285 * Returns the transaction instance associated with the current thread, 286 * creates a new one if it wasn't already. 287 * <p/> 288 * Transaction doesn't start until you call <tt>transaction.begin()</tt> and 289 * if a transaction is started then all transactional Hazelcast operations 290 * are automatically transactional. 291 * <pre> 292 * Map map = Hazelcast.getMap("mymap"); 293 * Transaction txn = Hazelcast.getTransaction(); 294 * txn.begin(); 295 * try { 296 * map.put ("key", "value"); 297 * txn.commit(); 298 * }catch (Exception e) { 299 * txn.rollback(); 300 * } 301 * </pre> 302 * Isolation is always <tt>REPEATABLE_READ</tt> . If you are in 303 * a transaction, you can read the data in your transaction and the data that 304 * is already committed and if not in a transaction, you can only read the 305 * committed data. Implementation is different for queue and map/set. For 306 * queue operations (offer,poll), offered and/or polled objects are copied to 307 * the next member in order to safely commit/rollback. For map/set, Hazelcast 308 * first acquires the locks for the write operations (put, remove) and holds 309 * the differences (what is added/removed/updated) locally for each transaction. 310 * When transaction is set to commit, Hazelcast will release the locks and 311 * apply the differences. When rolling back, Hazelcast will simply releases 312 * the locks and discard the differences. Transaction instance is attached 313 * to the current thread and each Hazelcast operation checks if the current 314 * thread holds a transaction, if so, operation will be transaction aware. 315 * When transaction is committed, rolled back or timed out, it will be detached 316 * from the thread holding it. 317 * 318 * @return transaction for the current thread 319 * 320 * @deprecated as of version 2.2 321 * @see #newHazelcastInstance(com.hazelcast.config.Config) 322 * @see HazelcastInstance#getTransaction() 323 */ 324 @Deprecated 325 public static Transaction getTransaction() { 326 return getDefaultInstance().getTransaction(); 327 } 328 329 /** 330 * Creates cluster-wide atomic long. Hazelcast AtomicNumber is a distributed 331 * implementation of <tt>java.util.concurrent.atomic.AtomicLong</tt>. 332 * 333 * @param name of the AtomicNumber proxy 334 * @return AtomicNumber proxy instance 335 * 336 * @deprecated as of version 2.2 337 * @see #newHazelcastInstance(com.hazelcast.config.Config) 338 * @see HazelcastInstance#getAtomicNumber(String) 339 */ 340 @Deprecated 341 public static AtomicNumber getAtomicNumber(String name) { 342 return getDefaultInstance().getAtomicNumber(name); 343 } 344 345 /** 346 * Creates a cluster-wide CountDownLatch. Hazelcast ICountDownLatch is a distributed 347 * implementation of <tt>java.util.concurrent.CountDownLatch</tt>. 348 * 349 * @param name of the distributed CountDownLatch 350 * @return ICountDownLatch proxy instance 351 * 352 * @deprecated as of version 2.2 353 * @see #newHazelcastInstance(com.hazelcast.config.Config) 354 * @see HazelcastInstance#getCountDownLatch(String) 355 */ 356 @Deprecated 357 public static ICountDownLatch getCountDownLatch(String name) { 358 return getDefaultInstance().getCountDownLatch(name); 359 } 360 361 /** 362 * Creates a cluster-wide semaphore. Hazelcast ISemaphore is a distributed 363 * implementation of <tt>java.util.concurrent.Semaphore</tt>. 364 * 365 * @param name of the distributed Semaphore 366 * @return ISemaphore proxy instance 367 * 368 * @deprecated as of version 2.2 369 * @see #newHazelcastInstance(com.hazelcast.config.Config) 370 * @see HazelcastInstance#getSemaphore(String) 371 */ 372 @Deprecated 373 public static ISemaphore getSemaphore(String name) { 374 return getDefaultInstance().getSemaphore(name); 375 } 376 377 /** 378 * Creates cluster-wide unique IDs. Generated IDs are long type primitive values 379 * between <tt>0</tt> and <tt>Long.MAX_VALUE</tt> . Id generation occurs almost at the speed of 380 * <tt>AtomicLong.incrementAndGet()</tt> . Generated IDs are unique during the life 381 * cycle of the cluster. If the entire cluster is restarted, IDs start from <tt>0</tt> again. 382 * 383 * @param name 384 * @return IdGenerator proxy instance 385 * 386 * @deprecated as of version 2.2 387 * @see #newHazelcastInstance(com.hazelcast.config.Config) 388 * @see HazelcastInstance#getIdGenerator(String) 389 */ 390 @Deprecated 391 public static IdGenerator getIdGenerator(String name) { 392 return getDefaultInstance().getIdGenerator(name); 393 } 394 395 /** 396 * Detaches this member from the cluster. 397 * It doesn't shutdown the entire cluster, it shuts down 398 * this local member only. 399 * 400 * @see HazelcastInstance#getLifecycleService() 401 * @see LifecycleService#shutdown() 402 * @deprecated as of version 1.9 403 */ 404 @Deprecated 405 public static void shutdown() { 406 synchronized (initLock) { 407 if (defaultInstance.get() != null) { 408 getDefaultInstance().shutdown(); 409 defaultInstance.set(null); 410 } 411 } 412 } 413 414 /** 415 * Shuts down all running Hazelcast Instances on this JVM, including the 416 * default one if it is running. It doesn't shutdown all members of the 417 * cluster but just the ones running on this JVM. 418 * 419 * @see #newHazelcastInstance(Config) 420 */ 421 public static void shutdownAll() { 422 com.hazelcast.impl.FactoryImpl.shutdownAll(); 423 synchronized (initLock) { 424 defaultInstance.set(null); 425 } 426 } 427 428 /** 429 * Detaches this member from the cluster first and then restarts it 430 * as a new member. 431 * 432 * @see HazelcastInstance##getLifecycleService() 433 * @see LifecycleService#restart() 434 * @deprecated as of version 1.9 435 */ 436 @Deprecated 437 public static void restart() { 438 synchronized (initLock) { 439 if (defaultInstance.get() != null) { 440 getLifecycleService().restart(); 441 } else { 442 getDefaultInstance(); 443 } 444 } 445 } 446 447 /** 448 * Returns all queue, map, set, list, topic, lock, multimap 449 * instances created by Hazelcast. 450 * 451 * @return the collection of instances created by Hazelcast. 452 * 453 * @deprecated as of version 2.2 454 * @see #newHazelcastInstance(com.hazelcast.config.Config) 455 * @see HazelcastInstance#getInstances() 456 */ 457 @Deprecated 458 public static Collection<Instance> getInstances() { 459 return getDefaultInstance().getInstances(); 460 } 461 462 /** 463 * Add a instance listener which will be notified when a 464 * new instance such as map, queue, multimap, topic, lock is 465 * added or removed. 466 * 467 * @param instanceListener instance listener 468 * 469 * @deprecated as of version 2.2 470 * @see #newHazelcastInstance(com.hazelcast.config.Config) 471 * @see HazelcastInstance#addInstanceListener(InstanceListener) 472 */ 473 @Deprecated 474 public static void addInstanceListener(InstanceListener instanceListener) { 475 getDefaultInstance().addInstanceListener(instanceListener); 476 } 477 478 /** 479 * Removes the specified instance listener. Returns silently 480 * if specified instance listener doesn't exist. 481 * 482 * @param instanceListener instance listener to remove 483 * 484 * @deprecated as of version 2.2 485 * @see #newHazelcastInstance(com.hazelcast.config.Config) 486 * @see HazelcastInstance#removeInstanceListener(InstanceListener) 487 */ 488 @Deprecated 489 public static void removeInstanceListener(InstanceListener instanceListener) { 490 getDefaultInstance().removeInstanceListener(instanceListener); 491 } 492 493 /** 494 * Creates a new HazelcastInstance (a new node in a cluster). 495 * This method allows you to create and run multiple instances 496 * of Hazelcast cluster members on the same JVM. 497 * <p/> 498 * To shutdown all running HazelcastInstances (all members on this JVM) 499 * call {@link #shutdownAll()}. 500 * 501 * @param config Configuration for the new HazelcastInstance (member) 502 * @return new HazelcastInstance 503 * @see #shutdownAll() 504 * @see #getHazelcastInstanceByName(String) 505 */ 506 public static HazelcastInstance newHazelcastInstance(Config config) { 507 return com.hazelcast.impl.FactoryImpl.newHazelcastInstanceProxy(config); 508 } 509 510 /** 511 * Creates a new HazelcastInstance (a new node in a cluster). 512 * This method allows you to create and run multiple instances 513 * of Hazelcast cluster members on the same JVM. 514 * <p/> 515 * To shutdown all running HazelcastInstances (all members on this JVM) 516 * call {@link #shutdownAll()}. 517 * 518 * Hazelcast will look into two places for the configuration file: 519 * <ol> 520 * <li> 521 * System property: Hazelcast will first check if "hazelcast.config" system property is set to a file path. 522 * Example: -Dhazelcast.config=C:/myhazelcast.xml. 523 * </li> 524 * <li> 525 * Classpath: If config file is not set as a system property, Hazelcast will check classpath for hazelcast.xml file. 526 * </li> 527 * </ol> 528 * If Hazelcast doesn't find any config file, it will happily start with default configuration (hazelcast-default.xml) 529 * located in hazelcast.jar. 530 * 531 * @return new HazelcastInstance 532 * @see #shutdownAll() 533 * @see #getHazelcastInstanceByName(String) 534 */ 535 public static HazelcastInstance newHazelcastInstance() { 536 return com.hazelcast.impl.FactoryImpl.newHazelcastInstanceProxy(null); 537 } 538 539 /** 540 * Creates a new HazelcastInstance Lite Member (a new node in a cluster). 541 * This method allows you to create and run multiple instances 542 * of Hazelcast cluster members on the same JVM. 543 * <p/> 544 * To shutdown all running HazelcastInstances (all members on this JVM) 545 * call {@link #shutdownAll()}. 546 * 547 * Hazelcast will look into two places for the configuration file: 548 * <ol> 549 * <li> 550 * System property: Hazelcast will first check if "hazelcast.config" system property is set to a file path. 551 * Example: -Dhazelcast.config=C:/myhazelcast.xml. 552 * </li> 553 * <li> 554 * Classpath: If config file is not set as a system property, Hazelcast will check classpath for hazelcast.xml file. 555 * </li> 556 * </ol> 557 * If Hazelcast doesn't find any config file, it will happily start with default configuration (hazelcast-default.xml) 558 * located in hazelcast.jar. 559 * 560 * @return new HazelcastInstance 561 * @see #shutdownAll() 562 * @see #getHazelcastInstanceByName(String) 563 */ 564 public static HazelcastInstance newLiteMemberHazelcastInstance() { 565 return com.hazelcast.impl.FactoryImpl.newHazelcastInstanceProxy(null, true); 566 } 567 568 /** 569 * Returns an existing HazelcastInstance with instanceName. 570 * <p/> 571 * To shutdown all running HazelcastInstances (all members on this JVM) 572 * call {@link #shutdownAll()}. 573 * 574 * @param instanceName Name of the HazelcastInstance (member) 575 * @return HazelcastInstance 576 * @see #newHazelcastInstance(Config) 577 * @see #shutdownAll() 578 */ 579 public static HazelcastInstance getHazelcastInstanceByName(String instanceName) { 580 return com.hazelcast.impl.FactoryImpl.getHazelcastInstanceProxy(instanceName); 581 } 582 583 /** 584 * Returns all active/running HazelcastInstances on this JVM. 585 * <p/> 586 * To shutdown all running HazelcastInstances (all members on this JVM) 587 * call {@link #shutdownAll()}. 588 * 589 * @return all HazelcastInstances 590 * @see #newHazelcastInstance(Config) 591 * @see #getHazelcastInstanceByName(String) 592 * @see #shutdownAll() 593 */ 594 public static Set<HazelcastInstance> getAllHazelcastInstances() { 595 return com.hazelcast.impl.FactoryImpl.getAllHazelcastInstanceProxies(); 596 } 597 598 /** 599 * Returns the configuration of this Hazelcast instance. 600 * 601 * @return configuration of this Hazelcast instance 602 * 603 * @deprecated as of version 2.2 604 * @see #newHazelcastInstance(com.hazelcast.config.Config) 605 * @see HazelcastInstance#getConfig() 606 */ 607 @Deprecated 608 public static Config getConfig() { 609 return getDefaultInstance().getConfig(); 610 } 611 612 /** 613 * Returns the partition service of this Hazelcast instance. 614 * PartitionService allows you to introspect current partitions in the 615 * cluster, partition owner members and listen for partition migration events. 616 * 617 * @return partition service 618 * 619 * @deprecated as of version 2.2 620 * @see #newHazelcastInstance(com.hazelcast.config.Config) 621 * @see HazelcastInstance#getPartitionService() 622 */ 623 @Deprecated 624 public static PartitionService getPartitionService() { 625 return getDefaultInstance().getPartitionService(); 626 } 627 628 /** 629 * Returns the logging service of this Hazelcast instance. 630 * LoggingService allows you to listen for LogEvents 631 * generated by Hazelcast runtime. You can log the events somewhere 632 * or take action base on the message. 633 * 634 * @return logging service 635 * 636 * @deprecated as of version 2.2 637 * @see #newHazelcastInstance(com.hazelcast.config.Config) 638 * @see HazelcastInstance#getLoggingService() 639 */ 640 @Deprecated 641 public static LoggingService getLoggingService() { 642 return getDefaultInstance().getLoggingService(); 643 } 644 645 /** 646 * Returns the lifecycle service for this instance. LifecycleService allows you 647 * to shutdown, restart, pause and resume this HazelcastInstance and listen for 648 * the lifecycle events. 649 * 650 * @return lifecycle service 651 * 652 * @deprecated as of version 2.2 653 * @see #newHazelcastInstance(com.hazelcast.config.Config) 654 * @see HazelcastInstance#getLifecycleService() 655 */ 656 @Deprecated 657 public static LifecycleService getLifecycleService() { 658 return getDefaultInstance().getLifecycleService(); 659 } 660 661 /** 662 * Sets <tt>OutOfMemoryHandler</tt> to be used when an <tt>OutOfMemoryError</tt> 663 * is caught by Hazelcast threads. 664 * 665 * <p> 666 * <b>Warning: </b> <tt>OutOfMemoryHandler</tt> may not be called although JVM throws 667 * <tt>OutOfMemoryError</tt>. 668 * Because error may be thrown from an external (user thread) thread 669 * and Hazelcast may not be informed about <tt>OutOfMemoryError</tt>. 670 * </p> 671 * 672 * @param outOfMemoryHandler 673 * 674 * @see OutOfMemoryError 675 * @see OutOfMemoryHandler 676 */ 677 public static void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler) { 678 com.hazelcast.impl.OutOfMemoryErrorDispatcher.setHandler(outOfMemoryHandler); 679 } 680}