akka.actor

Class UntypedActorWithStash

java.lang.Object

akka.actor.UntypedActor

akka.actor.UntypedActorWithStash

All Implemented Interfaces:

Actor, Stash, UnrestrictedStash, RequiresMessageQueue<DequeBasedMessageQueueSemantics>

public abstract class UntypedActorWithStash
extends UntypedActor
implements Stash

Actor base class that should be extended to create an actor with a stash.

The stash enables an actor to temporarily stash away messages that can not or should not be handled using the actor's current behavior.

Example:

   public class MyActorWithStash extends UntypedActorWithStash {
     int count = 0;
     public void onReceive(Object msg) {
       if (msg instanceof String) {
         if (count < 0) {
           getSender().tell(new Integer(((String) msg).length()), getSelf());
         } else if (count == 2) {
           count = -1;
           unstashAll();
         } else {
           count += 1;
           stash();
         }
       }
     }
   }
 

Note that the subclasses of UntypedActorWithStash by default request a Deque based mailbox since this class implements the RequiresMessageQueue marker interface. You can override the default mailbox provided when DequeBasedMessageQueueSemantics are requested via config:

   akka.actor.mailbox.requirements {
     "akka.dispatch.BoundedDequeBasedMessageQueueSemantics" = your-custom-mailbox
   }
 

Alternatively, you can add your own requirement marker to the actor and configure a mailbox type to be used for your marker.

For a Stash based actor that enforces unbounded deques see UntypedActorWithUnboundedStash. There is also an unrestricted version UntypedActorWithUnrestrictedStash that does not enforce the mailbox type.

Nested Class Summary

Nested classes/interfaces inherited from interface akka.actor.Actor

Actor.emptyBehavior$

Constructor Summary

Constructors

Constructor and Description
UntypedActorWithStash()

Method Summary

Methods

Modifier and Type	Method and Description
akka.actor.ActorCell	actorCell()
int	capacity()
scala.collection.immutable.Vector<Envelope>	clearStash() INTERNAL API.
ActorContext	context() INTERNAL API.
void	enqueueFirst(Envelope envelope) Enqueues envelope at the first position in the mailbox.
DequeBasedMessageQueueSemantics	mailbox() INTERNAL API.
void	prepend(scala.collection.immutable.Seq<Envelope> others) Prepends others to this stash.
ActorRef	self() INTERNAL API.
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 akka.actor.UntypedActor

getContext, getSelf, getSender, onReceive, postRestart, postStop, preRestart, preStart, receive, supervisorStrategy, unhandled

Methods inherited from class java.lang.Object

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

Methods inherited from interface akka.actor.UnrestrictedStash

postStop, preRestart

Methods inherited from interface akka.actor.Actor

aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, context, noSender, postRestart, preStart, receive, self, sender, supervisorStrategy, unhandled

Constructor Detail

UntypedActorWithStash

public UntypedActorWithStash()

Method Detail

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.