public interface Cluster
All the methods on the Cluster are thread-safe.
Modifier and Type | Method and Description |
---|---|
UUID |
addMembershipListener(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.
|
ClusterState |
getClusterState()
Returns the state of the cluster.
|
long |
getClusterTime()
Returns the cluster-wide time in milliseconds.
|
Version |
getClusterVersion()
The cluster version indicates the operating version of the cluster.
|
HotRestartService |
getHotRestartService()
Deprecated.
since 5.0
Use
getPersistenceService() instead. |
Member |
getLocalMember()
Returns this Hazelcast instance member.
|
Set<Member> |
getMembers()
Set of the current members in the cluster.
|
PersistenceService |
getPersistenceService()
Returns the public persistence service for interacting with Persistence
|
void |
promoteLocalLiteMember()
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 the
ClusterState.PASSIVE transactionally,
then triggers the shutdown process on each node. |
void |
shutdown(TransactionOptions transactionOptions)
Changes state of the cluster to the
ClusterState.PASSIVE transactionally, then
triggers the shutdown process on each node. |
UUID addMembershipListener(@Nonnull MembershipListener listener)
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
the InitialMembershipEvent
.
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.
listener
- membership listenerNullPointerException
- if listener is nullremoveMembershipListener(UUID)
boolean removeMembershipListener(@Nonnull UUID registrationId)
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.
registrationId
- the registrationId of MembershipListener to removeNullPointerException
- if the registration ID is nulladdMembershipListener(MembershipListener)
Set<Member> getMembers()
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()'.
Member getLocalMember()
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.
void promoteLocalLiteMember()
getLocalMember()
and getMembers()
reflect the promotion.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/repartitioninglong getClusterTime()
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.
@Nonnull ClusterState getClusterState()
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.
void changeClusterState(@Nonnull ClusterState newState)
TWO_PHASE
and will have 1 durability by default. If you want to override
transaction options, use changeClusterState(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
to FROZEN
or PASSIVE
will fail with an IllegalStateException
.
If transaction timeouts during state change, then this method will fail with a TransactionException
.
newState
- new state of the clusterNullPointerException
- if newState is nullIllegalArgumentException
- if newState is ClusterState.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 timeoutsvoid changeClusterState(@Nonnull ClusterState newState, @Nonnull TransactionOptions transactionOptions)
TWO_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
to FROZEN
or PASSIVE
will fail with an IllegalStateException
.
If transaction timeouts during state change, then this method will fail with a TransactionException
.
newState
- new state of the clustertransactionOptions
- transaction optionsNullPointerException
- if newState is nullIllegalArgumentException
- if newState is ClusterState.IN_TRANSITION
or transaction type is not TWO_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 timeoutsVersion getClusterVersion()
LifecycleEvent.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 on
hazelcast-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.
@Deprecated HotRestartService getHotRestartService()
getPersistenceService()
instead.PersistenceService getPersistenceService()
UnsupportedOperationException
- if the persistence service is not
supported on this instance (e.g. on client)void shutdown()
ClusterState.PASSIVE
transactionally,
then triggers the shutdown process on each node. Transaction will be TWO_PHASE
and will have 1 durability by default. If you want to override transaction options,
use shutdown(TransactionOptions)
.
If the cluster is already in ClusterState.PASSIVE
, shutdown process begins immediately.
All the node join / leave rules described in ClusterState.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.
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 timeoutsClusterProperty.CLUSTER_SHUTDOWN_TIMEOUT_SECONDS
,
changeClusterState(ClusterState)
,
ClusterState.PASSIVE
void shutdown(@Nullable TransactionOptions transactionOptions)
ClusterState.PASSIVE
transactionally, then
triggers the shutdown process on each node. Transaction must be a TWO_PHASE
transaction.
If the cluster is already in ClusterState.PASSIVE
, shutdown process begins immediately.
All the node join / leave rules described in ClusterState.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.
transactionOptions
- transaction optionsIllegalStateException
- 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 timeoutsClusterProperty.CLUSTER_SHUTDOWN_TIMEOUT_SECONDS
,
changeClusterState(ClusterState)
,
ClusterState.PASSIVE
void changeClusterVersion(@Nonnull Version version)
changeClusterState(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 by
NodeExtension.isNodeVersionCompatibleWith(Version)
, then a
VersionMismatchException
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 being ClusterState.IN_TRANSITION
, disallowing membership changes until the new cluster version is
committed.
version
- new version of the clustervoid changeClusterVersion(@Nonnull Version version, @Nonnull TransactionOptions options)
changeClusterState(ClusterState, TransactionOptions)
. The transaction
options must specify a TWO_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 by
NodeExtension.isNodeVersionCompatibleWith(Version)
, then a
VersionMismatchException
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 being ClusterState.IN_TRANSITION
, disallowing membership changes until the new cluster version is
committed.
version
- new version of the clusteroptions
- options by which to execute the transactionCopyright © 2023 Hazelcast, Inc.. All rights reserved.