com.hazelcast.core

Interface Cluster

All Known Subinterfaces:

ClusterService

All Known Implementing Classes:

ClientClusterProxy, ClusterServiceImpl

public interface Cluster

Hazelcast cluster interface. It provides access to the members in the cluster and one can register for changes in the cluster members.

All the methods on the Cluster are thread-safe.

Method Summary

Methods

Modifier and Type	Method and Description
String	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.
ClusterState	getClusterState() Returns the state of the cluster.
long	getClusterTime() Returns the cluster-wide time in milliseconds.
Member	getLocalMember() Returns this Hazelcast instance member.
Set<Member>	getMembers() Set of the current members in the cluster.
boolean	removeMembershipListener(String 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.

Method Detail

addMembershipListener

String addMembershipListener(MembershipListener listener)

Adds MembershipListener to listen for membership updates.

The addMembershipListener method returns a register-id. This id is needed to remove the MembershipListener using the removeMembershipListener(String) 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.

Parameters:

listener - membership listener

Returns:

the registration id.

Throws:

NullPointerException - if listener is null.

See Also:

removeMembershipListener(String)

removeMembershipListener

boolean removeMembershipListener(String registrationId)

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:

addMembershipListener(MembershipListener)

getMembers

Set<Member> 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

Member getLocalMember()

Returns this Hazelcast instance member.

Returns:

this Hazelcast instance member

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

ClusterState 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.

Returns:

state of the cluster

Since:

3.6

changeClusterState

void changeClusterState(ClusterState newState)

Changes state of the cluster to the given state transactionally. Transaction will be 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.

Parameters:

newState - new state of the cluster

Throws:

NullPointerException - if newState is null

IllegalArgumentException - if newState is ClusterState.IN_TRANSITION

IllegalStateException - if member-list changes during the transaction or there are ongoing/pending migration operations

TransactionException - if there's already an ongoing transaction or this transaction fails or this transaction timeouts

Since:

3.6

changeClusterState

void changeClusterState(ClusterState newState,
                      TransactionOptions transactionOptions)

Changes state of the cluster to the given state transactionally. Transaction must be a 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.

Parameters:

newState - new state of the cluster

transactionOptions - transaction options

Throws:

NullPointerException - if newState is null

IllegalArgumentException - 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 operations

TransactionException - if there's already an ongoing transaction or this transaction fails or this transaction timeouts

Since:

3.6

shutdown

void shutdown()

Changes state of the cluster to the 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. If some of the nodes do not shutdown before the timeout duration, shutdown can be also invoked on them.

Throws:

IllegalStateException - if member-list changes during the transaction or there are ongoing/pending migration operations

TransactionException - if there's already an ongoing transaction or this transaction fails or this transaction timeouts

Since:

3.6

See Also:

com.hazelcast.instance.GroupProperty#CLUSTER_SHUTDOWN_TIMEOUT_SECONDS}, #changeClusterState(ClusterState)}, ClusterState#PASSIVE}

shutdown

void shutdown(TransactionOptions transactionOptions)

Changes state of the cluster to the 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. If some of the nodes do not shutdown before the timeout duration, shutdown can be also invoked on them.

Parameters:

transactionOptions - transaction options

Throws:

IllegalStateException - if member-list changes during the transaction or there are ongoing/pending migration operations

TransactionException - if there's already an ongoing transaction or this transaction fails or this transaction timeouts

Since:

3.6

See Also:

com.hazelcast.instance.GroupProperty#CLUSTER_SHUTDOWN_TIMEOUT_SECONDS}, #changeClusterState(ClusterState)}, ClusterState#PASSIVE}