akka.contrib.pattern
Class ClusterSingletonProxy

java.lang.Object
  extended by akka.contrib.pattern.ClusterSingletonProxy
All Implemented Interfaces:
Actor, ActorLogging, Stash, StashSupport, UnrestrictedStash, RequiresMessageQueue<DequeBasedMessageQueueSemantics>

public class ClusterSingletonProxy
extends java.lang.Object
implements Actor, Stash, ActorLogging

The ClusterSingletonProxy works together with the ClusterSingletonManager to provide a distributed proxy to the singleton actor.

The proxy can be started on every node where the singleton needs to be reached and used as if it were the singleton itself. It will then act as a router to the currently running singleton instance. If the singleton is not currently available, e.g., during hand off or startup, the proxy will stash the messages sent to the singleton and then unstash them when the singleton is finally available. The proxy mixes in the Stash trait, so it can be configured accordingly.

The proxy works by keeping track of the oldest cluster member. When a new oldest member is identified, e.g., because the older one left the cluster, or at startup, the proxy will try to identify the singleton on the oldest member by periodically sending an Identify message until the singleton responds with its ActorIdentity.

Note that this is a best effort implementation: messages can always be lost due to the distributed nature of the actors involved.

param: singletonPathString The logical path of the singleton. This does not include the node address or actor system name, e.g., it can be something like /user/singletonManager/singleton. param: role Cluster role on which the singleton is deployed. This is required to keep track only of the members where the singleton can actually exist. param: singletonIdentificationInterval Periodicity at which the proxy sends the Identify message to the current singleton actor selection.


Nested Class Summary
 
Nested classes/interfaces inherited from interface akka.actor.Actor
Actor.emptyBehavior$
 
Constructor Summary
ClusterSingletonProxy(java.lang.String singletonPathString, scala.Option<java.lang.String> role, scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
           
 
Method Summary
 void add(Member m)
          Adds new member if it has the right role.
 scala.math.Ordering<Member> ageOrdering()
           
 void cancelTimer()
           
 Cluster cluster()
           
 java.lang.String createIdentifyId(int i)
           
static Props defaultProps(java.lang.String singletonPath, java.lang.String role)
          Java API: Factory method for ClusterSingletonProxy Props.
 void handleInitial(ClusterEvent.CurrentClusterState state)
           
 int identifyCounter()
           
 java.lang.String identifyId()
           
 void identifySingleton()
          Discard old singleton ActorRef and send a periodic message to self to identify the singleton.
 scala.Option<Cancellable> identifyTimer()
           
 boolean matchingRole(Member member)
           
 scala.collection.immutable.SortedSet<Member> membersByAge()
           
 void postStop()
          User overridable callback.
 void preStart()
          User overridable callback.
static Props props(java.lang.String singletonPath, scala.Option<java.lang.String> role, scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
          Scala API: Factory method for ClusterSingletonProxy Props.
static Props props(java.lang.String singletonPath, java.lang.String role, scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
          Java API: Factory method for ClusterSingletonProxy Props.
 scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive()
          This defines the initial actor behavior, it must return a partial function with the actor logic.
 void remove(Member m)
          Removes a member.
 scala.Option<ActorRef> singleton()
           
 java.lang.String[] singletonPath()
           
 void trackChange(scala.Function0<scala.runtime.BoxedUnit> block)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface akka.actor.Actor
aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, context, postRestart, self, sender, supervisorStrategy, unhandled
 
Methods inherited from interface akka.actor.StashSupport
actorCell, capacity, clearStash, context, enqueueFirst, mailbox, prepend, self, stash, theStash, unstash, unstashAll, unstashAll
 
Methods inherited from interface akka.actor.ActorLogging
_log, log
 

Constructor Detail

ClusterSingletonProxy

public ClusterSingletonProxy(java.lang.String singletonPathString,
                             scala.Option<java.lang.String> role,
                             scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
Method Detail

props

public static Props props(java.lang.String singletonPath,
                          scala.Option<java.lang.String> role,
                          scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
Scala API: Factory method for ClusterSingletonProxy Props.

Parameters:
singletonPath - The logical path of the singleton, i.e., /user/singletonManager/singleton.
role - The role of the cluster nodes where the singleton can be deployed. If None, then any node will do.
singletonIdentificationInterval - Interval at which the proxy will try to resolve the singleton instance.
Returns:
The singleton proxy Props.

props

public static Props props(java.lang.String singletonPath,
                          java.lang.String role,
                          scala.concurrent.duration.FiniteDuration singletonIdentificationInterval)
Java API: Factory method for ClusterSingletonProxy Props.

Parameters:
singletonPath - The logical path of the singleton, i.e., /user/singletonManager/singleton.
role - The role of the cluster nodes where the singleton can be deployed. If null, then any node will do.
singletonIdentificationInterval - Interval at which the proxy will try to resolve the singleton instance.
Returns:
The singleton proxy Props.

defaultProps

public static Props defaultProps(java.lang.String singletonPath,
                                 java.lang.String role)
Java API: Factory method for ClusterSingletonProxy Props. The interval at which the proxy will try to resolve the singleton instance is set to 1 second.

Parameters:
singletonPath - The logical path of the singleton, i.e., /user/singletonManager/singleton.
role - The role of the cluster nodes where the singleton can be deployed. If null, then any node will do.
Returns:
The singleton proxy Props.

singletonPath

public java.lang.String[] singletonPath()

identifyCounter

public int identifyCounter()

identifyId

public java.lang.String identifyId()

createIdentifyId

public java.lang.String createIdentifyId(int i)

identifyTimer

public scala.Option<Cancellable> identifyTimer()

cluster

public Cluster cluster()

singleton

public scala.Option<ActorRef> singleton()

ageOrdering

public scala.math.Ordering<Member> ageOrdering()

membersByAge

public scala.collection.immutable.SortedSet<Member> membersByAge()

preStart

public void preStart()
Description copied from interface: Actor
User overridable callback.

Is called when an Actor is started. Actors are automatically started asynchronously when created. Empty default implementation.

Specified by:
preStart in interface Actor

postStop

public void postStop()
Description copied from interface: Actor
User overridable callback.

Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation.

Specified by:
postStop in interface Actor
Specified by:
postStop in interface UnrestrictedStash

cancelTimer

public void cancelTimer()

matchingRole

public boolean matchingRole(Member member)

handleInitial

public void handleInitial(ClusterEvent.CurrentClusterState state)

identifySingleton

public void identifySingleton()
Discard old singleton ActorRef and send a periodic message to self to identify the singleton.


trackChange

public void trackChange(scala.Function0<scala.runtime.BoxedUnit> block)

add

public void add(Member m)
Adds new member if it has the right role.

Parameters:
m - New cluster member.

remove

public void remove(Member m)
Removes a member.

Parameters:
m - Cluster member to remove.

receive

public scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive()
Description copied from interface: Actor
This defines the initial actor behavior, it must return a partial function with the actor logic.

Specified by:
receive in interface Actor
Returns:
(undocumented)