akka.contrib.pattern
Class ClusterClient

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

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

This actor is intended to be used on an external node that is not member of the cluster. It acts like a gateway for sending messages to actors somewhere in the cluster. From the initial contact points it will establish a connection to a ClusterReceptionist somewhere in the cluster. It will monitor the connection to the receptionist and establish a new connection if the link goes down. When looking for a new receptionist it uses fresh contact points retrieved from previous establishment, or periodically refreshed contacts, i.e. not necessarily the initial contact points.

You can send messages via the ClusterClient to any actor in the cluster that is registered in the ClusterReceptionist. Messages are wrapped in ClusterClient.Send, ClusterClient.SendToAll or ClusterClient.Publish.

1. ClusterClient.Send - The message will be delivered to one recipient with a matching path, if any such exists. If several entries match the path the message will be delivered to one random destination. The sender of the message can specify that local affinity is preferred, i.e. the message is sent to an actor in the same local actor system as the used receptionist actor, if any such exists, otherwise random to any other matching entry.

2. ClusterClient.SendToAll - The message will be delivered to all recipients with a matching path.

3. ClusterClient.Publish - The message will be delivered to all recipients Actors that have been registered as subscribers to to the named topic.

Use the factory method props(scala.collection.immutable.Set, scala.concurrent.duration.FiniteDuration, scala.concurrent.duration.FiniteDuration)) to create the Props for the actor.


Nested Class Summary
static class ClusterClient.Publish
           
static class ClusterClient.Publish$
           
static class ClusterClient.Send
           
static class ClusterClient.Send$
           
static class ClusterClient.SendToAll
          Convenience constructor with localAffinity false
static class ClusterClient.SendToAll$
           
 
Nested classes/interfaces inherited from interface akka.actor.Actor
Actor.emptyBehavior$
 
Constructor Summary
ClusterClient(scala.collection.immutable.Set<ActorSelection> initialContacts, scala.concurrent.duration.FiniteDuration establishingGetContactsInterval, scala.concurrent.duration.FiniteDuration refreshContactsInterval)
           
 
Method Summary
 scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> active(ActorRef receptionist)
           
 akka.actor.ActorCell actorCell()
           
 int capacity()
           
 scala.collection.immutable.Vector<Envelope> clearStash()
          INTERNAL API.
 scala.collection.immutable.IndexedSeq<ActorSelection> contacts()
           
 ActorContext context()
          INTERNAL API.
static Props defaultProps(java.util.Set<ActorSelection> initialContacts)
          Java API: Factory method for ClusterClient Props with default values.
 void enqueueFirst(Envelope envelope)
          Enqueues envelope at the first position in the mailbox.
 scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> establishing()
           
 DequeBasedMessageQueueSemantics mailbox()
          INTERNAL API.
 void postStop()
          User overridable callback.
 void prepend(scala.collection.immutable.Seq<Envelope> others)
          Prepends others to this stash.
static Props props(scala.collection.immutable.Set<ActorSelection> initialContacts, scala.concurrent.duration.FiniteDuration establishingGetContactsInterval, scala.concurrent.duration.FiniteDuration refreshContactsInterval)
          Scala API: Factory method for ClusterClient Props.
static Props props(java.util.Set<ActorSelection> initialContacts, scala.concurrent.duration.FiniteDuration establishingGetContactsInterval, scala.concurrent.duration.FiniteDuration refreshContactsInterval)
          Java API: Factory method for ClusterClient 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.
 scala.Option<Cancellable> refreshContactsTask()
           
 void scheduleRefreshContactsTick(scala.concurrent.duration.FiniteDuration interval)
           
 ActorRef self()
          INTERNAL API.
 void sendGetContacts()
           
 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 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, preStart, self, sender, supervisorStrategy, unhandled
 
Methods inherited from interface akka.actor.ActorLogging
_log, log
 

Constructor Detail

ClusterClient

public ClusterClient(scala.collection.immutable.Set<ActorSelection> initialContacts,
                     scala.concurrent.duration.FiniteDuration establishingGetContactsInterval,
                     scala.concurrent.duration.FiniteDuration refreshContactsInterval)
Method Detail

props

public static Props props(scala.collection.immutable.Set<ActorSelection> initialContacts,
                          scala.concurrent.duration.FiniteDuration establishingGetContactsInterval,
                          scala.concurrent.duration.FiniteDuration refreshContactsInterval)
Scala API: Factory method for ClusterClient Props.


props

public static Props props(java.util.Set<ActorSelection> initialContacts,
                          scala.concurrent.duration.FiniteDuration establishingGetContactsInterval,
                          scala.concurrent.duration.FiniteDuration refreshContactsInterval)
Java API: Factory method for ClusterClient Props.


defaultProps

public static Props defaultProps(java.util.Set<ActorSelection> initialContacts)
Java API: Factory method for ClusterClient Props with default values.


contacts

public scala.collection.immutable.IndexedSeq<ActorSelection> contacts()

refreshContactsTask

public scala.Option<Cancellable> refreshContactsTask()

scheduleRefreshContactsTick

public void scheduleRefreshContactsTick(scala.concurrent.duration.FiniteDuration interval)

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

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

establishing

public scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> establishing()

active

public scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> active(ActorRef receptionist)

sendGetContacts

public void sendGetContacts()

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.