Interface Cluster
All the methods on the Cluster are thread-safe.
-
Method Summary
Modifier and TypeMethodDescriptionaddMembershipListener
(MembershipListener listener) Adds MembershipListener to listen for membership updates.void
changeClusterState
(ClusterState newState) Changes state of the cluster to the given state transactionally.void
changeClusterState
(ClusterState newState, TransactionOptions transactionOptions) Changes state of the cluster to the given state transactionally.void
changeClusterVersion
(Version version) Changes the cluster version transactionally.void
changeClusterVersion
(Version version, TransactionOptions options) Changes the cluster version transactionally, with the transaction options provided.void
Demotes the local data member to a lite member.Returns the state of the cluster.long
Returns the cluster-wide time in milliseconds.The cluster version indicates the operating version of the cluster.Deprecated.Returns this Hazelcast instance member.Set of the current members in the cluster.Returns the public persistence service for interacting with Persistencevoid
Promotes the local lite member to a data member.boolean
removeMembershipListener
(UUID registrationId) Removes the specified MembershipListener.void
shutdown()
Changes state of the cluster to theClusterState.PASSIVE
transactionally, then triggers the shutdown process on each node.void
shutdown
(TransactionOptions transactionOptions) Changes state of the cluster to theClusterState.PASSIVE
transactionally, then triggers the shutdown process on each node.
-
Method Details
-
addMembershipListener
Adds MembershipListener to listen for membership updates.The addMembershipListener method returns a registration ID. This ID is needed to remove the MembershipListener using the
removeMembershipListener(UUID)
method.If the MembershipListener implements the
InitialMembershipListener
interface, it will also receive theInitialMembershipEvent
.There is no check for duplicate registrations, so if you register the listener twice, it will get events twice. The listener doesn't notify when a lite member is promoted to a data member.
- Parameters:
listener
- membership listener- Returns:
- the registration ID
- Throws:
NullPointerException
- if listener is null- See Also:
-
removeMembershipListener
Removes the specified MembershipListener.If the same MembershipListener is registered multiple times, it needs to be removed multiple times. This method can safely be called multiple times for the same registration ID; subsequent calls are ignored.
- Parameters:
registrationId
- the registrationId of MembershipListener to remove- Returns:
- true if the registration is removed, false otherwise
- Throws:
NullPointerException
- if the registration ID is null- See Also:
-
getMembers
Set of the current members in the cluster. The returned set is an immutable set; it can't be modified.The returned set is backed by an ordered set. Every member in the cluster returns the 'members' in the same order. To obtain the oldest member (the master) in the cluster, you can retrieve the first item in the set using 'getMembers().iterator().next()'.
- Returns:
- current members in the cluster
-
getLocalMember
Returns this Hazelcast instance member.The returned value will never be null, but it may change when local lite member is promoted to a data member via
promoteLocalLiteMember()
or when this member merges to a new cluster after split-brain detected. Returned value should not be cached but instead this method should be called each time when local member is needed.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Returns:
- this Hazelcast instance member
-
promoteLocalLiteMember
void promoteLocalLiteMember()Promotes the local lite member to a data member. When this method returns, bothgetLocalMember()
andgetMembers()
reflect the promotion.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Throws:
IllegalStateException
- when member is not a lite member or mastership claim is in progress or local member cannot be identified as a member of the cluster or cluster state doesn't allow migrations/repartitioning- Since:
- 3.9
-
demoteLocalDataMember
void demoteLocalDataMember()Demotes the local data member to a lite member. When this method returns, bothgetLocalMember()
andgetMembers()
reflect the demotion.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Throws:
IllegalStateException
- when member is not a data member or mastership claim is in progress or local member cannot be identified as a member of the cluster or cluster state doesn't allow migrations/repartitioning or the member is the only data member in the cluster.- Since:
- 5.4
-
getClusterTime
long getClusterTime()Returns the cluster-wide time in milliseconds.Cluster tries to keep a cluster-wide time which might be different than the member's own system time. Cluster-wide time is -almost- the same on all members of the cluster.
- Returns:
- cluster-wide time
-
getClusterState
Returns the state of the cluster.If cluster state change is in process,
ClusterState.IN_TRANSITION
will be returned.This is a local operation, state will be read directly from local member.
Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Returns:
- state of the cluster
- Since:
- 3.6
-
changeClusterState
Changes state of the cluster to the given state transactionally. Transaction will beTWO_PHASE
and will have 1 durability by default. If you want to override transaction options, usechangeClusterState(ClusterState, TransactionOptions)
.If the given state is already same as current state of the cluster, then this method will have no effect.
If there's an ongoing state change transaction in the cluster, this method will fail immediately with a
TransactionException
.If a membership change occurs in the cluster during state change, a new member joins or an existing member leaves, then this method will fail with an
IllegalStateException
.If there are ongoing/pending migration/replication operations, because of re-balancing due to member join or leave, then trying to change from
ACTIVE
toFROZEN
orPASSIVE
will fail with anIllegalStateException
.If transaction timeouts during state change, then this method will fail with a
TransactionException
.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Parameters:
newState
- new state of the cluster- Throws:
NullPointerException
- if newState is nullIllegalArgumentException
- if newState isClusterState.IN_TRANSITION
IllegalStateException
- if member-list changes during the transaction or there are ongoing/pending migration operationsTransactionException
- if there's already an ongoing transaction or this transaction fails or this transaction timeouts- Since:
- 3.6
-
changeClusterState
void changeClusterState(@Nonnull ClusterState newState, @Nonnull TransactionOptions transactionOptions) Changes state of the cluster to the given state transactionally. Transaction must be aTWO_PHASE
transaction.If the given state is already same as current state of the cluster, then this method will have no effect.
If there's an ongoing state change transaction in the cluster, this method will fail immediately with a
TransactionException
.If a membership change occurs in the cluster during state change, a new member joins or an existing member leaves, then this method will fail with an
IllegalStateException
.If there are ongoing/pending migration/replication operations, because of re-balancing due to member join or leave, then trying to change from
ACTIVE
toFROZEN
orPASSIVE
will fail with anIllegalStateException
.If transaction timeouts during state change, then this method will fail with a
TransactionException
.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Parameters:
newState
- new state of the clustertransactionOptions
- transaction options- Throws:
NullPointerException
- if newState is nullIllegalArgumentException
- if newState isClusterState.IN_TRANSITION
or transaction type is notTWO_PHASE
IllegalStateException
- if member-list changes during the transaction or there are ongoing/pending migration operationsTransactionException
- if there's already an ongoing transaction or this transaction fails or this transaction timeouts- Since:
- 3.6
-
getClusterVersion
The cluster version indicates the operating version of the cluster. It is separate from each node's codebase version, as it may be acceptable for a node to operate at a different compatibility version than its codebase version. This method may return Version.UNKNOWN if invoked after the ClusterService is constructed and before the node forms a cluster, either by joining existing members or becoming master of its standalone cluster if it is the first node on the cluster. Importantly, this is the time during which a lifecycle event with stateLifecycleEvent.LifecycleState.STARTING
is triggered.For example, consider a cluster comprised of nodes running on
hazelcast-3.8.0.jar
. Each node's codebase version is 3.8.0 and on startup the cluster version is 3.8. After a while, another node joins, running onhazelcast-3.9.jar
; this node's codebase version is 3.9.0. If deemed compatible, it is allowed to join the cluster. At this point, the cluster version is still 3.8 and the 3.9.0 member should be able to adapt its behaviour to be compatible with the other 3.8.0 members. Once all 3.8.0 members have been shutdown and replaced by other members on codebase version 3.9.0, still the cluster version will be 3.8. At this point, it is possible to update the cluster version to 3.9, since all cluster members will be compatible with the new cluster version. Once cluster version is updated to 3.9, further communication among members will take place in 3.9 and all new features and functionality of version 3.9 will be available.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Returns:
- the version at which this cluster operates.
- Since:
- 3.8
-
getHotRestartService
Deprecated.since 5.0 UsegetPersistenceService()
instead.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
. -
getPersistenceService
Returns the public persistence service for interacting with PersistenceSupported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Returns:
- the persistence service
- Throws:
UnsupportedOperationException
- if the persistence service is not supported on this instance (e.g. on client)- Since:
- 5.0
-
shutdown
void shutdown()Changes state of the cluster to theClusterState.PASSIVE
transactionally, then triggers the shutdown process on each node. Transaction will beTWO_PHASE
and will have 1 durability by default. If you want to override transaction options, useshutdown(TransactionOptions)
.If the cluster is already in
ClusterState.PASSIVE
, shutdown process begins immediately. All the node join / leave rules described inClusterState.PASSIVE
state also applies here.Any node can start the shutdown process. A shutdown command is sent to other nodes periodically until either all other nodes leave the cluster or a configurable timeout occurs (see
ClusterProperty.CLUSTER_SHUTDOWN_TIMEOUT_SECONDS
). If some of the nodes do not shutdown before the timeout duration, shutdown can be also invoked on them.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Throws:
IllegalStateException
- if member-list changes during the transaction or there are ongoing/pending migration operations or shutdown process times outTransactionException
- if there's already an ongoing transaction or this transaction fails or this transaction timeouts- Since:
- 3.6
- See Also:
-
shutdown
Changes state of the cluster to theClusterState.PASSIVE
transactionally, then triggers the shutdown process on each node. Transaction must be aTWO_PHASE
transaction.If the cluster is already in
ClusterState.PASSIVE
, shutdown process begins immediately. All the node join / leave rules described inClusterState.PASSIVE
state also applies here.Any node can start the shutdown process. A shutdown command is sent to other nodes periodically until either all other nodes leave the cluster or a configurable timeout occurs (see
ClusterProperty.CLUSTER_SHUTDOWN_TIMEOUT_SECONDS
). If some of the nodes do not shutdown before the timeout duration, shutdown can be also invoked on them.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Parameters:
transactionOptions
- transaction options- Throws:
IllegalStateException
- if member-list changes during the transaction or there are ongoing/pending migration operations or shutdown process times outTransactionException
- if there's already an ongoing transaction or this transaction fails or this transaction timeouts- Since:
- 3.6
- See Also:
-
changeClusterVersion
Changes the cluster version transactionally. Internally this method uses the same transaction infrastructure aschangeClusterState(ClusterState)
and the transaction defaults are the same in this case as well (TWO_PHASE
transaction with durability 1 by default).If the requested cluster version is same as the current one, nothing happens.
If a member of the cluster is not compatible with the given cluster
version
, as implemented byNodeExtension.isNodeVersionCompatibleWith(Version)
, then aVersionMismatchException
is thrown.If an invalid version transition is requested, for example changing to a different major version, an
IllegalArgumentException
is thrown.If a membership change occurs in the cluster during locking phase, a new member joins or an existing member leaves, then this method will fail with an
IllegalStateException
.Likewise, once locking phase is completed successfully,
getClusterState()
will report beingClusterState.IN_TRANSITION
, disallowing membership changes until the new cluster version is committed.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Parameters:
version
- new version of the cluster- Since:
- 3.8
-
changeClusterVersion
Changes the cluster version transactionally, with the transaction options provided. Internally this method uses the same transaction infrastructure aschangeClusterState(ClusterState, TransactionOptions)
. The transaction options must specify aTWO_PHASE
transaction.If the requested cluster version is same as the current one, nothing happens.
If a member of the cluster is not compatible with the given cluster
version
, as implemented byNodeExtension.isNodeVersionCompatibleWith(Version)
, then aVersionMismatchException
is thrown.If an invalid version transition is requested, for example changing to a different major version, an
IllegalArgumentException
is thrown.If a membership change occurs in the cluster during locking phase, a new member joins or an existing member leaves, then this method will fail with an
IllegalStateException
.Likewise, once locking phase is completed successfully,
getClusterState()
will report beingClusterState.IN_TRANSITION
, disallowing membership changes until the new cluster version is committed.Supported only for members of the cluster, clients will throw a
UnsupportedOperationException
.- Parameters:
version
- new version of the clusteroptions
- options by which to execute the transaction- Since:
- 3.8
-
getPersistenceService()
instead.