akka.actor
Class ActorRef

java.lang.Object
  akka.actor.ActorRef

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<ActorRef>

Direct Known Subclasses:

InternalActorRef

public abstract class ActorRef
extends java.lang.Object
implements java.lang.Comparable<ActorRef>, scala.Serializable

Immutable and serializable handle to an actor, which may or may not reside on the local host or inside the same ActorSystem. An ActorRef can be obtained from an ActorRefFactory, an interface which is implemented by ActorSystem and ActorContext. This means actors can be created top-level in the ActorSystem or as children of an existing actor, but only from within that actor.

ActorRefs can be freely shared among actors by message passing. Message passing conversely is their only purpose, as demonstrated in the following examples:

Scala:

 import akka.pattern.ask

 class ExampleActor extends Actor {
   val other = context.actorOf(Props[OtherActor], "childName") // will be destroyed and re-created upon restart by default

   def receive {
     case Request1(msg) => other ! refine(msg)     // uses this actor as sender reference, reply goes to us
     case Request2(msg) => other.tell(msg, sender()) // forward sender reference, enabling direct reply
     case Request3(msg) =>
       implicit val timeout = Timeout(5.seconds)
       sender() ! (other ? msg)  // will reply with a Future for holding other's reply
   }
 }
 

Java:

 import static akka.pattern.Patterns.ask;

 public class ExampleActor Extends UntypedActor {
   // this child will be destroyed and re-created upon restart by default
   final ActorRef other = getContext().actorOf(Props.create(OtherActor.class), "childName");

   @Override
   public void onReceive(Object o) {
     if (o instanceof Request1) {
       Msg msg = ((Request1) o).getMsg();
       other.tell(msg, getSelf()); // uses this actor as sender reference, reply goes to us

     } else if (o instanceof Request2) {
       Msg msg = ((Request2) o).getMsg();
       other.tell(msg, getSender()); // forward sender reference, enabling direct reply

     } else if (o instanceof Request3) {
       Msg msg = ((Request3) o).getMsg();
       getSender().tell(ask(other, msg, 5000)); // reply with Future for holding the other's reply (timeout 5 seconds)

     } else {
       unhandled(o);
     }
   }
 }
 

ActorRef does not have a method for terminating the actor it points to, use ActorRefFactory.stop(ref), or send a PoisonPill, for this purpose.

Two actor references are compared equal when they have the same path and point to the same actor incarnation. A reference pointing to a terminated actor doesn't compare equal to a reference pointing to another (re-created) actor with the same path. Actor references acquired with actorFor do not always include the full information about the underlying actor identity and therefore such references do not always compare equal to references acquired with actorOf, sender, or context.self.

If you need to keep track of actor references in a collection and do not care about the exact actor incarnation you can use the ActorPath as key because the unique id of the actor is not taken into account when comparing actor paths.

See Also:

Serialized Form

Constructor Summary

ActorRef()

Method Summary

int	compareTo(ActorRef other) Comparison takes path and the unique id of the actor cell into account.
boolean	equals(java.lang.Object that) Equals takes path and the unique id of the actor cell into account.
void	forward(java.lang.Object message, ActorContext context) Forwards the message and passes the original sender actor as the sender.
int	hashCode()
abstract boolean	isTerminated() Is the actor shut down? The contract is that if this method returns true, then it will never be false again.
static ActorRef	noSender() Use this value as an argument to tell(java.lang.Object, akka.actor.ActorRef) if there is not actor to reply to (e.g.
abstract ActorPath	path() Returns the path for this actor (from this actor up to the root actor).
void	tell(java.lang.Object msg, ActorRef sender) Sends the specified message to the sender, i.e.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ActorRef

public ActorRef()

Method Detail

noSender

public static final ActorRef noSender()

Use this value as an argument to tell(java.lang.Object, akka.actor.ActorRef) if there is not actor to reply to (e.g. when sending from non-actor code).

Returns:

(undocumented)

path

public abstract ActorPath path()

Returns the path for this actor (from this actor up to the root actor).

Returns:

(undocumented)

compareTo

public final int compareTo(ActorRef other)

Comparison takes path and the unique id of the actor cell into account.

Specified by:

compareTo in interface java.lang.Comparable<ActorRef>

Parameters:

other - (undocumented)

Returns:

(undocumented)

tell

public final void tell(java.lang.Object msg,
                       ActorRef sender)

Sends the specified message to the sender, i.e. fire-and-forget semantics, including the sender reference if possible.

Pass akka.actor.ActorRef$.noSender or null as sender if there is nobody to reply to

Parameters:

msg - (undocumented)

sender - (undocumented)

forward

public void forward(java.lang.Object message,
                    ActorContext context)

Forwards the message and passes the original sender actor as the sender.

Works, no matter whether originally sent with tell/'!' or ask/'?'.

Parameters:

message - (undocumented)

context - (undocumented)

isTerminated

public abstract boolean isTerminated()

Is the actor shut down? The contract is that if this method returns true, then it will never be false again. But you cannot rely on that it is alive if it returns false, since this by nature is a racy method.

Returns:

(undocumented)

hashCode

public final int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public final boolean equals(java.lang.Object that)

Equals takes path and the unique id of the actor cell into account.

Overrides:

equals in class java.lang.Object

Parameters:

that - (undocumented)

Returns:

(undocumented)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object