akka.cluster

Class Cluster

java.lang.Object

akka.cluster.Cluster

All Implemented Interfaces:

Extension

public class Cluster
extends java.lang.Object
implements Extension

This module is responsible cluster membership information. Changes to the cluster information is retrieved through subscribe(akka.actor.ActorRef, java.lang.Class<?>...). Commands to operate the cluster is available through methods in this class, such as join(akka.actor.Address), down(akka.actor.Address) and leave(akka.actor.Address).

Each cluster Member is identified by its Address, and the cluster address of this actor system is selfAddress(). A member also has a status; initially MemberStatus Joining followed by MemberStatus Up.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Cluster.InfoLogger$ INTERNAL API

Constructor Summary

Constructors

Constructor and Description
Cluster(ExtendedActorSystem system)

Method Summary

Modifier and Type	Method and Description
ActorRef	clusterCore() INTERNAL API
static Cluster	createExtension(ExtendedActorSystem system)
void	down(Address address) Send command to DOWN the node specified by 'address'.
DowningProvider	downingProvider()
FailureDetectorRegistry<Address>	failureDetector()
static Cluster	get(ActorSystem system)
java.util.Set<java.lang.String>	getSelfRoles() Java API: roles that this member has
Cluster.InfoLogger$	InfoLogger() Accessor for nested Scala object
static boolean	isAssertInvariantsEnabled() INTERNAL API
boolean	isTerminated() Returns true if this cluster instance has be shutdown.
void	join(Address address) Try to join this cluster node with the node specified by 'address'.
void	joinSeedNodes(java.util.List<Address> seedNodes) Java API
void	joinSeedNodes(scala.collection.immutable.Seq<Address> seedNodes) Join the specified seed nodes without defining them in config.
void	leave(Address address) Send command to issue state transition to LEAVING for the node specified by 'address'.
static Cluster$	lookup()
ClusterReadView	readView()
<T> void	registerOnMemberRemoved(scala.Function0<T> code) The supplied thunk will be run, once, when current cluster member is Removed.
void	registerOnMemberRemoved(java.lang.Runnable callback) Java API: The supplied thunk will be run, once, when current cluster member is Removed.
<T> void	registerOnMemberUp(scala.Function0<T> code) The supplied thunk will be run, once, when current cluster member is Up.
void	registerOnMemberUp(java.lang.Runnable callback) Java API: The supplied callback will be run, once, when current cluster member is Up.
ActorPath	remotePathOf(ActorRef actorRef) Generate the remote actor path by replacing the Address in the RootActor Path for the given ActorRef with the cluster's selfAddress, unless address' host is already defined
Scheduler	scheduler() INTERNAL API
Address	selfAddress() The address of this cluster member.
scala.collection.immutable.Set<java.lang.String>	selfRoles() roles that this member has
UniqueAddress	selfUniqueAddress() The address including a uid of this cluster member.
void	sendCurrentClusterState(ActorRef receiver) Send current (full) state of the cluster to the specified receiver.
ClusterSettings	settings()
void	shutdown() INTERNAL API.
ClusterEvent.CurrentClusterState	state() Current snapshot state of the cluster.
void	subscribe(ActorRef subscriber, java.lang.Class<?>... to) Subscribe to one or more cluster domain events.
void	subscribe(ActorRef subscriber, ClusterEvent.SubscriptionInitialStateMode initialStateMode, java.lang.Class<?>... to) Subscribe to one or more cluster domain events.
void	subscribe(ActorRef subscriber, ClusterEvent.SubscriptionInitialStateMode initialStateMode, scala.collection.Seq<java.lang.Class<?>> to) Subscribe to one or more cluster domain events.
void	subscribe(ActorRef subscriber, scala.collection.Seq<java.lang.Class<?>> to) Subscribe to one or more cluster domain events.
ExtendedActorSystem	system()
void	unsubscribe(ActorRef subscriber) Unsubscribe to all cluster domain events.
void	unsubscribe(ActorRef subscriber, java.lang.Class<?> to) Unsubscribe to a specific type of cluster domain events, matching previous subscribe registration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Cluster

public Cluster(ExtendedActorSystem system)

Method Detail

get

public static Cluster get(ActorSystem system)

lookup

public static Cluster$ lookup()

createExtension

public static Cluster createExtension(ExtendedActorSystem system)

isAssertInvariantsEnabled

public static final boolean isAssertInvariantsEnabled()

INTERNAL API

Returns:

(undocumented)

InfoLogger

public Cluster.InfoLogger$ InfoLogger()

Accessor for nested Scala object

Returns:

(undocumented)

subscribe

public void subscribe(ActorRef subscriber,
                      java.lang.Class<?>... to)

Subscribe to one or more cluster domain events. The to classes can be ClusterEvent.ClusterDomainEvent or subclasses.

A snapshot of ClusterEvent.CurrentClusterState will be sent to the subscriber as the first message.

Parameters:

subscriber - (undocumented)

to - (undocumented)

subscribe

public void subscribe(ActorRef subscriber,
                      ClusterEvent.SubscriptionInitialStateMode initialStateMode,
                      java.lang.Class<?>... to)

Subscribe to one or more cluster domain events. The to classes can be ClusterEvent.ClusterDomainEvent or subclasses.

If initialStateMode is ClusterEvent.InitialStateAsEvents the events corresponding to the current state will be sent to the subscriber to mimic what you would have seen if you were listening to the events when they occurred in the past.

If initialStateMode is ClusterEvent.InitialStateAsSnapshot a snapshot of ClusterEvent.CurrentClusterState will be sent to the subscriber as the first message.

Note that for large clusters it is more efficient to use InitialStateAsSnapshot.

Parameters:

subscriber - (undocumented)

initialStateMode - (undocumented)

to - (undocumented)

system

public ExtendedActorSystem system()

settings

public ClusterSettings settings()

selfUniqueAddress

public UniqueAddress selfUniqueAddress()

The address including a uid of this cluster member. The uid is needed to be able to distinguish different incarnations of a member with same hostname and port.

Returns:

(undocumented)

selfAddress

public Address selfAddress()

The address of this cluster member.

Returns:

(undocumented)

selfRoles

public scala.collection.immutable.Set<java.lang.String> selfRoles()

roles that this member has

Returns:

(undocumented)

getSelfRoles

public java.util.Set<java.lang.String> getSelfRoles()

Java API: roles that this member has

Returns:

(undocumented)

failureDetector

public FailureDetectorRegistry<Address> failureDetector()

downingProvider

public DowningProvider downingProvider()

scheduler

public Scheduler scheduler()

INTERNAL API

Returns:

(undocumented)

clusterCore

public ActorRef clusterCore()

INTERNAL API

Returns:

(undocumented)

readView

public ClusterReadView readView()

isTerminated

public boolean isTerminated()

Returns true if this cluster instance has be shutdown.

Returns:

(undocumented)

state

public ClusterEvent.CurrentClusterState state()

Current snapshot state of the cluster.

Returns:

(undocumented)

subscribe

public void subscribe(ActorRef subscriber,
                      scala.collection.Seq<java.lang.Class<?>> to)

Subscribe to one or more cluster domain events. The to classes can be ClusterEvent.ClusterDomainEvent or subclasses.

A snapshot of ClusterEvent.CurrentClusterState will be sent to the subscriber as the first message.

Parameters:

subscriber - (undocumented)

to - (undocumented)

subscribe

public void subscribe(ActorRef subscriber,
                      ClusterEvent.SubscriptionInitialStateMode initialStateMode,
                      scala.collection.Seq<java.lang.Class<?>> to)

Subscribe to one or more cluster domain events. The to classes can be ClusterEvent.ClusterDomainEvent or subclasses.

If initialStateMode is ClusterEvent.InitialStateAsEvents the events corresponding to the current state will be sent to the subscriber to mimic what you would have seen if you were listening to the events when they occurred in the past.

If initialStateMode is ClusterEvent.InitialStateAsSnapshot a snapshot of ClusterEvent.CurrentClusterState will be sent to the subscriber as the first message.

Note that for large clusters it is more efficient to use InitialStateAsSnapshot.

Parameters:

subscriber - (undocumented)

initialStateMode - (undocumented)

to - (undocumented)

unsubscribe

public void unsubscribe(ActorRef subscriber)

Unsubscribe to all cluster domain events.

Parameters:

subscriber - (undocumented)

unsubscribe

public void unsubscribe(ActorRef subscriber,
                        java.lang.Class<?> to)

Unsubscribe to a specific type of cluster domain events, matching previous subscribe registration.

Parameters:

subscriber - (undocumented)

to - (undocumented)

sendCurrentClusterState

public void sendCurrentClusterState(ActorRef receiver)

Send current (full) state of the cluster to the specified receiver. If you want this to happen periodically you need to schedule a call to this method yourself. Note that you can also retrieve the current state with state().

Parameters:

receiver - (undocumented)

join

public void join(Address address)

Try to join this cluster node with the node specified by 'address'. A 'Join(selfAddress)' command is sent to the node to join.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

The name of the ActorSystem must be the same for all members of a cluster.

Parameters:

address - (undocumented)

joinSeedNodes

public void joinSeedNodes(scala.collection.immutable.Seq<Address> seedNodes)

Join the specified seed nodes without defining them in config. Especially useful from tests when Addresses are unknown before startup time.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Parameters:

seedNodes - (undocumented)

joinSeedNodes

public void joinSeedNodes(java.util.List<Address> seedNodes)

Java API

Join the specified seed nodes without defining them in config. Especially useful from tests when Addresses are unknown before startup time.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Parameters:

seedNodes - (undocumented)

leave

public void leave(Address address)

Send command to issue state transition to LEAVING for the node specified by 'address'. The member will go through the status changes MemberStatus Leaving (not published to subscribers) followed by MemberStatus Exiting and finally MemberStatus Removed.

Note that this command can be issued to any member in the cluster, not necessarily the one that is leaving. The cluster extension, but not the actor system or JVM, of the leaving member will be shutdown after the leader has changed status of the member to Exiting. Thereafter the member will be removed from the cluster. Normally this is handled automatically, but in case of network failures during this process it might still be necessary to set the node’s status to Down in order to complete the removal.

Parameters:

address - (undocumented)

down

public void down(Address address)

Send command to DOWN the node specified by 'address'.

When a member is considered by the failure detector to be unreachable the leader is not allowed to perform its duties, such as changing status of new joining members to 'Up'. The status of the unreachable member must be changed to 'Down', which can be done with this method.

Parameters:

address - (undocumented)

registerOnMemberUp

public <T> void registerOnMemberUp(scala.Function0<T> code)

The supplied thunk will be run, once, when current cluster member is Up. Typically used together with configuration option akka.cluster.min-nr-of-members to defer some action, such as starting actors, until the cluster has reached a certain size.

Parameters:

code - (undocumented)

registerOnMemberUp

public void registerOnMemberUp(java.lang.Runnable callback)

Java API: The supplied callback will be run, once, when current cluster member is Up. Typically used together with configuration option akka.cluster.min-nr-of-members to defer some action, such as starting actors, until the cluster has reached a certain size.

Parameters:

callback - (undocumented)

registerOnMemberRemoved

public <T> void registerOnMemberRemoved(scala.Function0<T> code)

The supplied thunk will be run, once, when current cluster member is Removed. If the cluster has already been shutdown the thunk will run on the caller thread immediately. Typically used together cluster.leave(cluster.selfAddress) and then system.terminate().

Parameters:

code - (undocumented)

registerOnMemberRemoved

public void registerOnMemberRemoved(java.lang.Runnable callback)

Java API: The supplied thunk will be run, once, when current cluster member is Removed. If the cluster has already been shutdown the thunk will run on the caller thread immediately. Typically used together cluster.leave(cluster.selfAddress) and then system.terminate().

Parameters:

callback - (undocumented)

remotePathOf

public ActorPath remotePathOf(ActorRef actorRef)

Generate the remote actor path by replacing the Address in the RootActor Path for the given ActorRef with the cluster's selfAddress, unless address' host is already defined

Parameters:

actorRef - (undocumented)

Returns:

(undocumented)

shutdown

public void shutdown()

INTERNAL API.

Shuts down all connections to other members, the cluster daemon and the periodic gossip and cleanup tasks.

Should not called by the user. The user can issue a LEAVE command which will tell the node to go through graceful handoff process LEAVE -> EXITING -> REMOVED -> SHUTDOWN.