akka.contrib.pattern
Class ClusterSingletonProxy

java.lang.Object
  extended by akka.contrib.pattern.ClusterSingletonProxy
All Implemented Interfaces:
Actor, ActorLogging, Stash, 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.


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
 akka.actor.ActorCell actorCell()
           
 void add(Member m)
          Adds new member if it has the right role.
 scala.math.Ordering<Member> ageOrdering()
           
 void cancelTimer()
           
 int capacity()
           
 scala.collection.immutable.Vector<Envelope> clearStash()
          INTERNAL API.
 Cluster cluster()
           
 ActorContext context()
          INTERNAL API.
 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 enqueueFirst(Envelope envelope)
          Enqueues envelope at the first position in the mailbox.
 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()
           
 DequeBasedMessageQueueSemantics mailbox()
          INTERNAL API.
 boolean matchingRole(Member member)
           
 scala.collection.immutable.SortedSet<Member> membersByAge()
           
 void postStop()
          User overridable callback.
 void prepend(scala.collection.immutable.Seq<Envelope> others)
          Prepends others to this stash.
 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.
 ActorRef self()
          INTERNAL API.
 scala.Option<ActorRef> singleton()
           
 java.lang.String[] singletonPath()
           
 void stash()
          Adds the current message (the message that the actor received last) to the actor's stash.
 scala.collection.immutable.Vector<Envelope> theStash()
           
 void trackChange(scala.Function0<scala.runtime.BoxedUnit> block)
           
 void unstash()
          Prepends the oldest message in the stash to the mailbox, and then removes that message from the stash.
 void unstashAll()
          Prepends all messages in the stash to the mailbox, and then clears the stash.
 void unstashAll(scala.Function1<java.lang.Object,java.lang.Object> filterPredicate)
          INTERNAL API.
 
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, noSender, postRestart, self, sender, supervisorStrategy, unhandled
 
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

context

public ActorContext context()
INTERNAL API.

Context of the actor that uses this stash.


self

public ActorRef self()
INTERNAL API.

Self reference of the actor that uses this stash.


theStash

public scala.collection.immutable.Vector<Envelope> theStash()

actorCell

public akka.actor.ActorCell actorCell()

capacity

public int capacity()

mailbox

public DequeBasedMessageQueueSemantics mailbox()
INTERNAL API.

The actor's deque-based message queue. mailbox.queue is the underlying Deque.


stash

public void stash()
Adds the current message (the message that the actor received last) to the actor's stash.

Throws:
StashOverflowException - in case of a stash capacity violation
java.lang.IllegalStateException - if the same message is stashed more than once

prepend

public void prepend(scala.collection.immutable.Seq<Envelope> others)
Prepends others to this stash. This method is optimized for a large stash and small others.


unstash

public void unstash()
Prepends the oldest message in the stash to the mailbox, and then removes that message from the stash.

Messages from the stash are enqueued to the mailbox until the capacity of the mailbox (if any) has been reached. In case a bounded mailbox overflows, a MessageQueueAppendFailedException is thrown.

The unstashed message is guaranteed to be removed from the stash regardless if the unstash() call successfully returns or throws an exception.


unstashAll

public void unstashAll()
Prepends all messages in the stash to the mailbox, and then clears the stash.

Messages from the stash are enqueued to the mailbox until the capacity of the mailbox (if any) has been reached. In case a bounded mailbox overflows, a MessageQueueAppendFailedException is thrown.

The stash is guaranteed to be empty after calling unstashAll().


unstashAll

public void unstashAll(scala.Function1<java.lang.Object,java.lang.Object> filterPredicate)
INTERNAL API.

Prepends selected messages in the stash, applying filterPredicate, to the mailbox, and then clears the stash.

Messages from the stash are enqueued to the mailbox until the capacity of the mailbox (if any) has been reached. In case a bounded mailbox overflows, a MessageQueueAppendFailedException is thrown.

The stash is guaranteed to be empty after calling unstashAll(Any => Boolean).

Parameters:
filterPredicate - only stashed messages selected by this predicate are prepended to the mailbox.

clearStash

public scala.collection.immutable.Vector<Envelope> clearStash()
INTERNAL API.

Clears the stash and and returns all envelopes that have not been unstashed.


enqueueFirst

public void enqueueFirst(Envelope envelope)
Enqueues envelope at the first position in the mailbox. If the message contained in the envelope is a Terminated message, it will be ensured that it can be re-received by the actor.