com.hazelcast.core

## Interface HazelcastInstance

- All Known Subinterfaces:
    HazelcastOSGiInstance
  All Known Implementing Classes:
    HazelcastInstanceImpl, HazelcastInstanceProxy

      public interface HazelcastInstance

  Hazelcast instance. Each instance is a member and/or client in a Hazelcast cluster. When you want to use Hazelcast's distributed data structures, you must first create an instance. Multiple Hazelcast instances can be created on a single JVM. Instances should be shut down explicitly. See the `shutdown()` method. If the instance is a client and you don't shut it down explicitly, it will continue to run and even connect to another live member if the one it was connected fails. Each Hazelcast instance has its own socket and threads.
  See Also:
    `Hazelcast.newHazelcastInstance(Config config)`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `addDistributedObjectListener(DistributedObjectListener distributedObjectListener)` Adds a Distributed Object listener which will be notified when a new `DistributedObject` will be created or destroyed.
    `<T> T` | `executeTransaction(TransactionalTask<T> task)` Executes the given transactional task in current thread using default options and returns the result of the task.
    `<T> T` | `executeTransaction(TransactionOptions options, TransactionalTask<T> task)` Executes the given transactional task in current thread using given options and returns the result of the task.
    `IAtomicLong` | `getAtomicLong(String name)` Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getAtomicLong(String)` instead. This method will be removed in Hazelcast 4.0.
    `<E> IAtomicReference<E>` | `getAtomicReference(String name)` Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getAtomicReference(String)` instead. This method will be removed in Hazelcast 4.0.
    `ICacheManager` | `getCacheManager()` Obtain the `ICacheManager` that provides access to JSR-107 (JCache) caches configured on a Hazelcast cluster.
    `CardinalityEstimator` | `getCardinalityEstimator(String name)` Obtain a `CardinalityEstimator` with the given name.
    `ClientService` | `getClientService()` Returns the client service of this Hazelcast instance.
    `Cluster` | `getCluster()` Returns the Cluster that this Hazelcast instance is part of.
    `Config` | `getConfig()` Returns the configuration of this Hazelcast instance.
    `ICountDownLatch` | `getCountDownLatch(String name)` Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getCountDownLatch(String)` instead. This method will be removed in Hazelcast 4.0.
    `CPSubsystem` | `getCPSubsystem()` Returns the CP subsystem that offers a set of in-memory linearizable data structures
    `<T extends DistributedObject> T` | `getDistributedObject(String serviceName, String name)`
    `Collection<DistributedObject>` | `getDistributedObjects()` Returns all `DistributedObject`s, that is all maps, queues, topics, locks etc.
    `DurableExecutorService` | `getDurableExecutorService(String name)` Creates or returns the durable executor service for the given name.
    `IExecutorService` | `getExecutorService(String name)` Creates or returns the distributed executor service for the given name.
    `FlakeIdGenerator` | `getFlakeIdGenerator(String name)` Creates or returns a cluster-wide unique ID generator.
    `IdGenerator` | `getIdGenerator(String name)` Deprecated. The implementation can produce duplicate IDs in case of network split, even with split-brain protection enabled (during short window while split-brain is detected). Use `getFlakeIdGenerator(String)` for an alternative implementation which does not suffer from this problem.
    `JobTracker` | `getJobTracker(String name)` Deprecated. MapReduce is deprecated and will be removed in 4.0. For map aggregations, you can use `Aggregator` on IMap. For general data processing, it is superseded by Hazelcast Jet.
    `LifecycleService` | `getLifecycleService()` Returns the lifecycle service for this instance.
    `<E> IList<E>` | `getList(String name)` Creates or returns the distributed list instance with the specified name.
    `Endpoint` | `getLocalEndpoint()` Returns the local Endpoint which this HazelcastInstance belongs to.
    `ILock` | `getLock(String key)` Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getLock(String)` instead. This method will be removed in Hazelcast 4.0.
    `LoggingService` | `getLoggingService()` Returns the logging service of this Hazelcast instance.
    `<K,V> IMap<K,V>` | `getMap(String name)` Creates or returns the distributed map instance with the specified name.
    `<K,V> MultiMap<K,V>` | `getMultiMap(String name)` Creates or returns the distributed multimap instance with the specified name.
    `String` | `getName()` Returns the name of this Hazelcast instance.
    `PartitionService` | `getPartitionService()` Returns the partition service of this Hazelcast instance.
    `PNCounter` | `getPNCounter(String name)` Creates or returns a `PNCounter` with the given name.
    `<E> IQueue<E>` | `getQueue(String name)` Creates or returns the distributed queue instance with the specified name.
    `QuorumService` | `getQuorumService()` Returns the quorum service of this Hazelcast instance.
    `<E> ITopic<E>` | `getReliableTopic(String name)` Creates or returns the reliable topic instance with the specified name.
    `<K,V> ReplicatedMap<K,V>` | `getReplicatedMap(String name)` Creates or returns the replicated map instance with the specified name.
    `<E> Ringbuffer<E>` | `getRingbuffer(String name)` Creates or returns the distributed Ringbuffer instance with the specified name.
    `IScheduledExecutorService` | `getScheduledExecutorService(String name)` Creates or returns the `IScheduledExecutorService` scheduled executor service for the given name.
    `ISemaphore` | `getSemaphore(String name)` Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getSemaphore(String)` instead. This method will be removed in Hazelcast 4.0.
    `<E> ISet<E>` | `getSet(String name)` Creates or returns the distributed set instance with the specified name.
    `<E> ITopic<E>` | `getTopic(String name)` Creates or returns the distributed topic instance with the specified name.
    `ConcurrentMap<String,Object>` | `getUserContext()` Returns a ConcurrentMap that can be used to add user-context to the HazelcastInstance.
    `HazelcastXAResource` | `getXAResource()` Gets xaResource which will participate in XATransaction.
    `TransactionContext` | `newTransactionContext()` Creates a new TransactionContext associated with the current thread using default options.
    `TransactionContext` | `newTransactionContext(TransactionOptions options)` Creates a new TransactionContext associated with the current thread with given options.
    `boolean` | `removeDistributedObjectListener(String registrationId)` Removes the specified Distributed Object listener.
    `void` | `shutdown()` Shuts down this HazelcastInstance.

- - ### Method Detail

    - #### getName

          String getName()

      Returns the name of this Hazelcast instance.
      Returns:
        name of this Hazelcast instance

    - #### getQueue

          <E> IQueue<E> getQueue(String name)

      Creates or returns the distributed queue instance with the specified name.
      Parameters:
        `name` - name of the distributed queue
      Returns:
        distributed queue instance with the specified name

    - #### getTopic

          <E> ITopic<E> getTopic(String name)

      Creates or returns the distributed topic instance with the specified name.
      Parameters:
        `name` - name of the distributed topic
      Returns:
        distributed topic instance with the specified name

    - #### getSet

          <E> ISet<E> getSet(String name)

      Creates or returns the distributed set instance with the specified name.
      Parameters:
        `name` - name of the distributed set
      Returns:
        distributed set instance with the specified name

    - #### getList

          <E> IList<E> getList(String name)

      Creates or returns the distributed list instance with the specified name. Index based operations on the list are not supported.
      Parameters:
        `name` - name of the distributed list
      Returns:
        distributed list instance with the specified name

    - #### getMap

          <K,V> IMap<K,V> getMap(String name)

      Creates or returns the distributed map instance with the specified name.
      Parameters:
        `name` - name of the distributed map
      Returns:
        distributed map instance with the specified name

    - #### getReplicatedMap

          <K,V> ReplicatedMap<K,V> getReplicatedMap(String name)

      Creates or returns the replicated map instance with the specified name.
      Parameters:
        `name` - name of the distributed map
      Returns:
        replicated map instance with specified name
      Throws:
        `ReplicatedMapCantBeCreatedOnLiteMemberException` - if it is called on a lite member
      Since:
        3.2

    - #### getJobTracker

          JobTracker getJobTracker(String name)

      Deprecated. MapReduce is deprecated and will be removed in 4.0. For map aggregations, you can use `Aggregator` on IMap. For general data processing, it is superseded by Hazelcast Jet.
      Creates or returns the job tracker instance with the specified name.
      Parameters:
        `name` - name of the job tracker
      Returns:
        job tracker instance with the specified name
      Since:
        3.2

    - #### getMultiMap

          <K,V> MultiMap<K,V> getMultiMap(String name)

      Creates or returns the distributed multimap instance with the specified name.
      Parameters:
        `name` - name of the distributed multimap
      Returns:
        distributed multimap instance with the specified name

    - #### getLock

          @Deprecated
          ILock getLock(String key)

      Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getLock(String)` instead. This method will be removed in Hazelcast 4.0.
      Creates or returns the distributed lock instance for the specified key object. The specified object is considered to be the key for this lock. So keys are considered equals cluster-wide as long as they are serialized to the same byte array such as String, long, Integer.

      Locks are fail-safe. If a member holds a lock and some of the members go down, the cluster will keep your locks safe and available. Moreover, when a member leaves the cluster, all the locks acquired by this dead member will be removed so that these locks can be available for live members immediately.

           Lock lock = hazelcastInstance.getLock("PROCESS_LOCK");
           lock.lock();
           try {
             // process
           } finally {
             lock.unlock();
           }

      Parameters:
        `key` - key of the lock instance
      Returns:
        distributed lock instance for the specified key.

    - #### getRingbuffer

          <E> Ringbuffer<E> getRingbuffer(String name)

      Creates or returns the distributed Ringbuffer instance with the specified name.
      Parameters:
        `name` - name of the distributed Ringbuffer
      Returns:
        distributed RingBuffer instance with the specified name

    - #### getReliableTopic

          <E> ITopic<E> getReliableTopic(String name)

      Creates or returns the reliable topic instance with the specified name.
      Parameters:
        `name` - name of the reliable topic
      Returns:
        the reliable topic

    - #### getCluster

          Cluster getCluster()

      Returns the Cluster that this Hazelcast instance is part of. Cluster interface allows you to add a listener for membership events and to learn more about the cluster that this Hazelcast instance is part of.
      Returns:
        the cluster that this Hazelcast instance is part of

    - #### getLocalEndpoint

          Endpoint getLocalEndpoint()

      Returns the local Endpoint which this HazelcastInstance belongs to.

      Returned endpoint will be a `Member` instance for cluster nodes and a `Client` instance for clients.

      Returns:
        the local `Endpoint` which this HazelcastInstance belongs to
      See Also:
        `Member`, `Client`

    - #### getExecutorService

          IExecutorService getExecutorService(String name)

      Creates or returns the distributed executor service for the given name. Executor service enables you to run your `Runnable`s and `Callable`s on the Hazelcast cluster.

      Note: Note that it doesn't support `invokeAll/Any` and doesn't have standard shutdown behavior

      Parameters:
        `name` - name of the executor service
      Returns:
        the distributed executor service for the given name

    - #### getDurableExecutorService

          DurableExecutorService getDurableExecutorService(String name)

      Creates or returns the durable executor service for the given name. DurableExecutor service enables you to run your `Runnable`s and `Callable`s on the Hazelcast cluster.

      Note: Note that it doesn't support `invokeAll/Any` and doesn't have standard shutdown behavior

      Parameters:
        `name` - name of the executor service
      Returns:
        the durable executor service for the given name

    - #### executeTransaction

          <T> T executeTransaction(TransactionalTask<T> task)
                            throws TransactionException

      Executes the given transactional task in current thread using default options and returns the result of the task.
      Type Parameters:
        `T` - return type of task
      Parameters:
        `task` - the transactional task to be executed
      Returns:
        result of the transactional task
      Throws:
        `TransactionException` - if an error occurs during transaction.

    - #### executeTransaction

          <T> T executeTransaction(TransactionOptions options,
                                   TransactionalTask<T> task)
                            throws TransactionException

      Executes the given transactional task in current thread using given options and returns the result of the task.
      Type Parameters:
        `T` - return type of task
      Parameters:
        `options` - options for this transactional task
        `task` - task to be executed
      Returns:
        result of the transactional task
      Throws:
        `TransactionException` - if an error occurs during transaction.

    - #### newTransactionContext

          TransactionContext newTransactionContext()

      Creates a new TransactionContext associated with the current thread using default options.
      Returns:
        new TransactionContext associated with the current thread

    - #### newTransactionContext

          TransactionContext newTransactionContext(TransactionOptions options)

      Creates a new TransactionContext associated with the current thread with given options.
      Parameters:
        `options` - options for this transaction
      Returns:
        new TransactionContext associated with the current thread

    - #### getIdGenerator

          @Deprecated
          IdGenerator getIdGenerator(String name)

      Deprecated. The implementation can produce duplicate IDs in case of network split, even with split-brain protection enabled (during short window while split-brain is detected). Use `getFlakeIdGenerator(String)` for an alternative implementation which does not suffer from this problem.
      Creates or returns a cluster-wide unique ID generator. Generated IDs are `long` primitive values between `0` and `Long.MAX_VALUE`. ID generation occurs almost at the speed of local `AtomicLong.incrementAndGet()`. Generated IDs are unique during the life cycle of the cluster. If the entire cluster is restarted, IDs start from `0` again.
      Parameters:
        `name` - name of the `IdGenerator`
      Returns:
        IdGenerator for the given name

    - #### getFlakeIdGenerator

          FlakeIdGenerator getFlakeIdGenerator(String name)

      Creates or returns a cluster-wide unique ID generator. Generated IDs are `long` primitive values and are k-ordered (roughly ordered). IDs are in the range from `0` to `Long.MAX_VALUE`.

      The IDs contain timestamp component and a node ID component, which is assigned when the member joins the cluster. This allows the IDs to be ordered and unique without any coordination between members, which makes the generator safe even in split-brain scenario (for caveats, `see here`).

      For more details and caveats, see class documentation for `FlakeIdGenerator`.

      Note: this implementation doesn't share namespace with `getIdGenerator(String)`. That is, `getIdGenerator("a")` is distinct from `getFlakeIdGenerator("a")`.

      Parameters:
        `name` - name of the `FlakeIdGenerator`
      Returns:
        FlakeIdGenerator for the given name

    - #### getAtomicLong

          @Deprecated
          IAtomicLong getAtomicLong(String name)

      Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getAtomicLong(String)` instead. This method will be removed in Hazelcast 4.0.
      Creates or returns a cluster-wide atomic long. Hazelcast `IAtomicLong` is distributed implementation of `java.util.concurrent.atomic.AtomicLong`.
      Parameters:
        `name` - name of the `IAtomicLong` proxy
      Returns:
        IAtomicLong proxy for the given name

    - #### getAtomicReference

          @Deprecated
          <E> IAtomicReference<E> getAtomicReference(String name)

      Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getAtomicReference(String)` instead. This method will be removed in Hazelcast 4.0.
      Creates or returns a cluster-wide atomic reference. Hazelcast `IAtomicReference` is distributed implementation of `java.util.concurrent.atomic.AtomicReference`.
      Parameters:
        `name` - name of the `IAtomicReference` proxy
      Returns:
        `IAtomicReference` proxy for the given name

    - #### getCountDownLatch

          @Deprecated
          ICountDownLatch getCountDownLatch(String name)

      Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getCountDownLatch(String)` instead. This method will be removed in Hazelcast 4.0.
      Creates or returns a cluster-wide CountDownLatch. Hazelcast `ICountDownLatch` is distributed implementation of `java.util.concurrent.CountDownLatch`.
      Parameters:
        `name` - name of the `ICountDownLatch` proxy
      Returns:
        `ICountDownLatch` proxy for the given name

    - #### getSemaphore

          @Deprecated
          ISemaphore getSemaphore(String name)

      Deprecated. This implementation may lose strong consistency in case of network failures or server failures. Please use `CPSubsystem.getSemaphore(String)` instead. This method will be removed in Hazelcast 4.0.
      Creates or returns a cluster-wide semaphore. Hazelcast `ISemaphore` is distributed implementation of `java.util.concurrent.Semaphore`.
      Parameters:
        `name` - name of the `ISemaphore` proxy
      Returns:
        `ISemaphore` proxy for the given name

    - #### getDistributedObjects

          Collection<DistributedObject> getDistributedObjects()

      Returns all `DistributedObject`s, that is all maps, queues, topics, locks etc.

      The results are returned on a best-effort basis. The result might miss just-created objects and contain just-deleted objects. An existing object can also be missing from the list occasionally. One cluster member is queried to obtain the list.

      Returns:
        the collection of all instances in the cluster

    - #### addDistributedObjectListener

          String addDistributedObjectListener(DistributedObjectListener distributedObjectListener)

      Adds a Distributed Object listener which will be notified when a new `DistributedObject` will be created or destroyed.
      Parameters:
        `distributedObjectListener` - instance listener
      Returns:
        returns registration ID

    - #### removeDistributedObjectListener

          boolean removeDistributedObjectListener(String registrationId)

      Removes the specified Distributed Object listener. Returns silently if the specified instance listener does not exist.
      Parameters:
        `registrationId` - ID of listener registration
      Returns:
        `true` if registration is removed, `false` otherwise

    - #### getConfig

          Config getConfig()

      Returns the configuration of this Hazelcast instance.
      Returns:
        configuration of this Hazelcast instance

    - #### getPartitionService

          PartitionService getPartitionService()

      Returns the partition service of this Hazelcast instance. InternalPartitionService allows you to introspect current partitions in the cluster, partition the owner members, and listen for partition migration events.
      Returns:
        the partition service of this Hazelcast instance

    - #### getQuorumService

          QuorumService getQuorumService()

      Returns the quorum service of this Hazelcast instance.

      Quorum service can be used to retrieve quorum callbacks which let you to notify quorum results of your own to the cluster quorum service. IMPORTANT: The term "quorum" simply refers to the count of members in the cluster required for an operation to succeed. It does NOT refer to an implementation of Paxos or Raft protocols as used in many NoSQL and distributed systems. The mechanism it provides in Hazelcast protects the user in case the number of nodes in a cluster drops below the specified one.

      Returns:
        the quorum service of this Hazelcast instance

    - #### getClientService

          ClientService getClientService()

      Returns the client service of this Hazelcast instance. Client service allows you to get information about connected clients.
      Returns:
        the `ClientService` of this Hazelcast instance.

    - #### getLoggingService

          LoggingService getLoggingService()

      Returns the logging service of this Hazelcast instance.

      LoggingService allows you to listen for LogEvents generated by Hazelcast runtime. You can log the events somewhere or take action based on the message.

      Returns:
        the logging service of this Hazelcast instance

    - #### getLifecycleService

          LifecycleService getLifecycleService()

      Returns the lifecycle service for this instance.

      LifecycleService allows you to shutdown this HazelcastInstance and listen for the lifecycle events.

      Returns:
        the lifecycle service for this instance

    - #### getDistributedObject

          <T extends DistributedObject> T getDistributedObject(String serviceName,
                                                               String name)

      Type Parameters:
        `T` - type of the DistributedObject
      Parameters:
        `serviceName` - name of the service
        `name` - name of the object
      Returns:
        DistributedObject created by the service

    - #### getUserContext

          ConcurrentMap<String,Object> getUserContext()

      Returns a ConcurrentMap that can be used to add user-context to the HazelcastInstance. This can be used to store dependencies that otherwise are hard to obtain. HazelcastInstance can be obtained by implementing a `HazelcastInstanceAware` interface when submitting a Runnable/Callable to Hazelcast ExecutorService. By storing the dependencies in the user-context, they can be retrieved as soon as you have a reference to the HazelcastInstance.

      This structure is purely local and Hazelcast remains agnostic abouts its content.

      Returns:
        a ConcurrentMap that can be used to add user-context to the HazelcastInstance.

    - #### getXAResource

          HazelcastXAResource getXAResource()

      Gets xaResource which will participate in XATransaction.
      Returns:
        the xaResource

    - #### getCacheManager

          ICacheManager getCacheManager()

      Obtain the `ICacheManager` that provides access to JSR-107 (JCache) caches configured on a Hazelcast cluster.

      Note that this method does not return a JCache `CacheManager`; to obtain a JCache `CacheManager` use JCache standard API.

      Returns:
        the Hazelcast `ICacheManager`
      See Also:
        `ICacheManager`

    - #### getCardinalityEstimator

          CardinalityEstimator getCardinalityEstimator(String name)

      Obtain a `CardinalityEstimator` with the given name.

      The estimator can be used to efficiently estimate the cardinality of unique entities in big data sets, without the need of storing them.

      The estimator is based on a HyperLogLog++ data-structure.

      Parameters:
        `name` - the name of the estimator
      Returns:
        a `CardinalityEstimator`

    - #### getPNCounter

          PNCounter getPNCounter(String name)

      Creates or returns a `PNCounter` with the given name.

      The PN counter can be used as a counter with strong eventual consistency guarantees - if operations to the counters stop, the counter values of all replicas that can communicate with each other should eventually converge to the same value.

      Parameters:
        `name` - the name of the PN counter
      Returns:
        a `PNCounter`

    - #### getScheduledExecutorService

          IScheduledExecutorService getScheduledExecutorService(String name)

      Creates or returns the `IScheduledExecutorService` scheduled executor service for the given name. ScheduledExecutor service enables you to schedule your `Runnable`s and `Callable`s on the Hazelcast cluster.
      Parameters:
        `name` - name of the executor service
      Returns:
        the scheduled executor service for the given name

    - #### getCPSubsystem

          CPSubsystem getCPSubsystem()

      Returns the CP subsystem that offers a set of in-memory linearizable data structures
      Returns:
        the CP subsystem that offers a set of in-memory linearizable data structures

    - #### shutdown

          void shutdown()

      Shuts down this HazelcastInstance. For more information see `LifecycleService.shutdown()`.

Copyright © 2019. All rights reserved.