akka.actor
Interface Actor

All Known Subinterfaces:
AsyncWriteJournal, Consumer, Creators.Act, Creators.ActWithStash, DiagnosticActorLogging, akka.persistence.Eventsourced, EventsourcedProcessor, FSM<S,D>, LoggingFSM<S,D>, Oneway, Processor, Producer, ProducerSupport, Recovery, SnapshotStore, Snapshotter, Stash, SyncWriteJournal, TestActorRefSpec.TActor, Transactor, UnboundedStash, UnrestrictedStash, View
All Known Implementing Classes:
AbstractActor, AbstractActorWithStash, AbstractActorWithUnboundedStash, AbstractActorWithUnrestrictedStash, AbstractEventsourcedProcessor, AbstractFSM, AbstractLoggingActor, AbstractLoggingFSM, AbstractProcessor, AbstractView, ActorTransportAdapterManager, AsyncWriteJournal, AsyncWriteJournal.Resequencer, Channel, ClusterClient, ClusterReceptionist, ClusterSingletonManager, ClusterSingletonProxy, DeadLetterListener, DefaultOSGiLogger, DistributedPubSubMediator, DurableMailboxSpecActorFactory.AccumulatorActor, DurableMailboxSpecActorFactory.MailboxTestActor, Inbox.InboxActor, JavaLogger, JavaLoggingEventHandler, Logging.DefaultLogger, Main.Terminator, PersistentChannel, ProducerSupport.ProducerChild, ReliableProxy, ReliableProxy.Receiver, ShardCoordinator, ShardCoordinatorSupervisor, ShardRegion, Slf4jLogger, SnapshotStore, SyncWriteJournal, TestActor, TestActorRefSpec.Logger, TestActorRefSpec.ReceiveTimeoutActor, TestActorRefSpec.ReplyActor, TestActorRefSpec.SenderActor, TestActorRefSpec.WorkerActor, TestEventListener, TimerBasedThrottler, UntypedActor, UntypedActorWithStash, UntypedActorWithUnboundedStash, UntypedActorWithUnrestrictedStash, UntypedConsumerActor, UntypedEventsourcedProcessor, UntypedProcessor, UntypedProducerActor, UntypedTransactor, UntypedView

public interface Actor

Actor base trait that should be extended by or mixed to create an Actor with the semantics of the 'Actor Model': http://en.wikipedia.org/wiki/Actor_model

An actor has a well-defined (non-cyclic) life-cycle. - ''RUNNING'' (created and started actor) - can receive messages - ''SHUTDOWN'' (when 'stop' is invoked) - can't do anything

The Actor's own ActorRef is available as self, the current message’s sender as sender() and the ActorContext as context. The only abstract method is receive which shall return the initial behavior of the actor as a partial function (behavior can be changed using context.become and context.unbecome).

This is the Scala API (hence the Scala code below), for the Java API see UntypedActor.


 class ExampleActor extends Actor {

   override val supervisorStrategy = OneForOneStrategy(maxNrOfRetries = 10, withinTimeRange = 1 minute) {
     case _: ArithmeticException      => Resume
     case _: NullPointerException     => Restart
     case _: IllegalArgumentException => Stop
     case _: Exception                => Escalate
   }

   def receive = {
                                      // directly calculated reply
     case Request(r)               => sender() ! calculate(r)

                                      // just to demonstrate how to stop yourself
     case Shutdown                 => context.stop(self)

                                      // error kernel with child replying directly to 'sender()'
     case Dangerous(r)             => context.actorOf(Props[ReplyToOriginWorker]).tell(PerformWork(r), sender())

                                      // error kernel with reply going through us
     case OtherJob(r)              => context.actorOf(Props[ReplyToMeWorker]) ! JobRequest(r, sender())
     case JobReply(result, orig_s) => orig_s ! result
   }
 }
 

The last line demonstrates the essence of the error kernel design: spawn one-off actors which terminate after doing their job, pass on sender() to allow direct reply if that is what makes sense, or round-trip the sender as shown with the fictitious JobRequest/JobReply message pair.

If you don’t like writing context you can always import context._ to get direct access to actorOf, stop etc. This is not default in order to keep the name-space clean.


Nested Class Summary
static class Actor.emptyBehavior$
          emptyBehavior is a Receive-expression that matches no messages at all, ever.
 
Method Summary
 void aroundPostRestart(java.lang.Throwable reason)
          Can be overridden to intercept calls to postRestart.
 void aroundPostStop()
          Can be overridden to intercept calls to postStop.
 void aroundPreRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message)
          Can be overridden to intercept calls to preRestart.
 void aroundPreStart()
          Can be overridden to intercept calls to preStart.
 void aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive, java.lang.Object msg)
          INTERNAL API.
 ActorContext context()
          Stores the context for this actor, including self, and sender.
 ActorRef noSender()
          Default placeholder (null) used for "!" to indicate that there is no sender of the message, that will be translated to the receiving system's deadLetters.
 void postRestart(java.lang.Throwable reason)
          User overridable callback: By default it calls preStart().
 void postStop()
          User overridable callback.
 void preRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message)
          User overridable callback: '''By default it disposes of all children and then calls postStop().'''
 void preStart()
          User overridable callback.
 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.
 ActorRef self()
          The 'self' field holds the ActorRef for this actor.
 ActorRef sender()
          The reference sender Actor of the last received message.
 SupervisorStrategy supervisorStrategy()
          User overridable definition the strategy to use for supervising child actors.
 void unhandled(java.lang.Object message)
          User overridable callback.
 

Method Detail

noSender

ActorRef noSender()
Default placeholder (null) used for "!" to indicate that there is no sender of the message, that will be translated to the receiving system's deadLetters.


context

ActorContext context()
Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

ActorContext is the Scala API. getContext returns a UntypedActorContext, which is the Java API of the actor context.


self

ActorRef self()
The 'self' field holds the ActorRef for this actor.

Can be used to send messages to itself:

 self ! message
 


sender

ActorRef sender()
The reference sender Actor of the last received message. Is defined if the message was sent from another Actor, else deadLetters in ActorSystem.

WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!


receive

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.


aroundReceive

void aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive,
                   java.lang.Object msg)
INTERNAL API.

Can be overridden to intercept calls to this actor's current behavior.

Parameters:
receive - current behavior.
msg - current message.

aroundPreStart

void aroundPreStart()
Can be overridden to intercept calls to preStart. Calls preStart by default.


aroundPostStop

void aroundPostStop()
Can be overridden to intercept calls to postStop. Calls postStop by default.


aroundPreRestart

void aroundPreRestart(java.lang.Throwable reason,
                      scala.Option<java.lang.Object> message)
Can be overridden to intercept calls to preRestart. Calls preRestart by default.


aroundPostRestart

void aroundPostRestart(java.lang.Throwable reason)
Can be overridden to intercept calls to postRestart. Calls postRestart by default.


supervisorStrategy

SupervisorStrategy supervisorStrategy()
User overridable definition the strategy to use for supervising child actors.


preStart

void preStart()
User overridable callback.

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


postStop

void postStop()
User overridable callback.

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


preRestart

void preRestart(java.lang.Throwable reason,
                scala.Option<java.lang.Object> message)
User overridable callback: '''By default it disposes of all children and then calls postStop().'''

Parameters:
reason - the Throwable that caused the restart to happen
message - optionally the current message the actor processed when failing, if applicable

Is called on a crashed Actor right BEFORE it is restarted to allow clean up of resources before Actor is terminated.


postRestart

void postRestart(java.lang.Throwable reason)
User overridable callback: By default it calls preStart().

Parameters:
reason - the Throwable that caused the restart to happen

Is called right AFTER restart on the newly created Actor to allow reinitialization after an Actor crash.


unhandled

void unhandled(java.lang.Object message)
User overridable callback.

Is called when a message isn't handled by the current behavior of the actor by default it fails with either a DeathPactException (in case of an unhandled Terminated message) or publishes an UnhandledMessage to the actor's system's EventStream