com.hazelcast.core

Interface HazelcastInstance

All Known Subinterfaces:

HazelcastOSGiInstance

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

Modifier and Type	Method and Description
UUID	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.
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.
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 DistributedObjects, 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.
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.
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.
<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.
<E> ISet<E>	getSet(String name) Creates or returns the distributed set instance with the specified name.
SplitBrainProtectionService	getSplitBrainProtectionService() Returns the split brain protection service of this Hazelcast instance.
SqlService	getSql() Returns a service to execute distributed SQL queries.
<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(UUID registrationId) Removes the specified Distributed Object listener.
void	shutdown() Shuts down this HazelcastInstance.

Method Detail

getName

@Nonnull
String getName()

Returns the name of this Hazelcast instance.

Returns:

name of this Hazelcast instance

getQueue

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

Creates or returns the distributed queue instance with the specified name.

Type Parameters:

E - queue item type

Parameters:

name - name of the distributed queue

Returns:

distributed queue instance with the specified name

getTopic

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

Creates or returns the distributed topic instance with the specified name.

Type Parameters:

E - the type of the topic message

Parameters:

name - name of the distributed topic

Returns:

distributed topic instance with the specified name

getSet

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

Creates or returns the distributed set instance with the specified name.

Type Parameters:

E - the type of elements maintained by the set

Parameters:

name - name of the distributed set

Returns:

distributed set instance with the specified name

getList

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

Creates or returns the distributed list instance with the specified name. Index based operations on the list are not supported.

Type Parameters:

E - the type of elements maintained by the list

Parameters:

name - name of the distributed list

Returns:

distributed list instance with the specified name

getMap

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

Creates or returns the distributed map instance with the specified name.

Type Parameters:

K - key type

V - value type

Parameters:

name - name of the distributed map

Returns:

distributed map instance with the specified name

getReplicatedMap

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

Creates or returns the replicated map instance with the specified name.

Type Parameters:

K - the type of keys maintained by the replicated map

V - the type of mapped values

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

getMultiMap

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

Creates or returns the distributed multimap instance with the specified name.

Type Parameters:

K - type of the multimap key

V - type of the multimap value

Parameters:

name - name of the distributed multimap

Returns:

distributed multimap instance with the specified name

getRingbuffer

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

Creates or returns the distributed Ringbuffer instance with the specified name.

Type Parameters:

E - the type of the elements that the Ringbuffer contains

Parameters:

name - name of the distributed Ringbuffer

Returns:

distributed RingBuffer instance with the specified name

getReliableTopic

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

Creates or returns the reliable topic instance with the specified name.

Type Parameters:

E - the type of the topic message

Parameters:

name - name of the reliable topic

Returns:

the reliable topic

getCluster

@Nonnull
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

@Nonnull
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

@Nonnull
IExecutorService getExecutorService(@Nonnull
                                             String name)

Creates or returns the distributed executor service for the given name. Executor service enables you to run your Runnables and Callables 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

@Nonnull
DurableExecutorService getDurableExecutorService(@Nonnull
                                                          String name)

Creates or returns the durable executor service for the given name. DurableExecutor service enables you to run your Runnables and Callables 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(@Nonnull
                         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(@Nonnull
                         TransactionOptions options,
                         @Nonnull
                         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(@Nonnull
                                         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

getFlakeIdGenerator

@Nonnull
FlakeIdGenerator getFlakeIdGenerator(@Nonnull
                                              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.

Parameters:

name - name of the FlakeIdGenerator

Returns:

FlakeIdGenerator for the given name

getDistributedObjects

Collection<DistributedObject> getDistributedObjects()

Returns all DistributedObjects, 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

UUID addDistributedObjectListener(@Nonnull
                                  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(@Nonnull
                                        UUID 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

@Nonnull
Config getConfig()

Returns the configuration of this Hazelcast instance.

Returns:

configuration of this Hazelcast instance

getPartitionService

@Nonnull
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

getSplitBrainProtectionService

@Nonnull
SplitBrainProtectionService getSplitBrainProtectionService()

Returns the split brain protection service of this Hazelcast instance.

Split brain protection service can be used to retrieve split brain protection callbacks which let you to notify split brain protection results of your own to the cluster split brain protection service.

Returns:

the split brain protection service of this Hazelcast instance

getClientService

@Nonnull
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

@Nonnull
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

@Nonnull
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

@Nonnull
<T extends DistributedObject> T getDistributedObject(@Nonnull
                                                              String serviceName,
                                                              @Nonnull
                                                              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

@Nonnull
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

@Nonnull
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

@Nonnull
CardinalityEstimator getCardinalityEstimator(@Nonnull
                                                      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

@Nonnull
PNCounter getPNCounter(@Nonnull
                                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

@Nonnull
IScheduledExecutorService getScheduledExecutorService(@Nonnull
                                                               String name)

Creates or returns the IScheduledExecutorService scheduled executor service for the given name. ScheduledExecutor service enables you to schedule your Runnables and Callables on the Hazelcast cluster.

Parameters:

name - name of the executor service

Returns:

the scheduled executor service for the given name

getCPSubsystem

@Nonnull
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

getSql

@Beta
 @Nonnull
SqlService getSql()

Returns a service to execute distributed SQL queries.

The service is in beta state. Behavior and API might be changed in future releases. Binary compatibility is not guaranteed between minor and patch releases.

Returns:

SQL service

See Also:

SqlService

shutdown

void shutdown()

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