Merge pull request #159 from jboner/wip-1516-ActorContext-cleanup-rk

remove non-user API from ActorContext, see #1516

akka-actor/src/main/scala/akka/actor/Actor.scala

@@ -307,7 +307,8 @@ trait Actor {
   // =========================================
 
   private[akka] final def apply(msg: Any) = {
-    val behaviorStack = context.hotswap
+    // FIXME this should all go into ActorCell
+    val behaviorStack = context.asInstanceOf[ActorCell].hotswap
     msg match {
       case msg if behaviorStack.nonEmpty && behaviorStack.head.isDefinedAt(msg) ⇒ behaviorStack.head.apply(msg)
       case msg if behaviorStack.isEmpty && processingBehavior.isDefinedAt(msg) ⇒ processingBehavior.apply(msg)

akka-actor/src/main/scala/akka/actor/ActorCell.scala

@@ -67,7 +67,7 @@ trait ActorContext extends ActorRefFactory {
   def setReceiveTimeout(timeout: Duration): Unit
 
   /**
-   * Resets the current receive timeout.
+   * Clears the receive timeout, i.e. deactivates this feature.
    */
   def resetReceiveTimeout(): Unit
 
@@ -83,16 +83,6 @@ trait ActorContext extends ActorRefFactory {
    */
   def unbecome(): Unit
 
-  /**
-   * Returns the current message envelope.
-   */
-  def currentMessage: Envelope
-
-  /**
-   * Returns a stack with the hotswapped behaviors (as Scala PartialFunction).
-   */
-  def hotswap: Stack[PartialFunction[Any, Unit]]
-
   /**
    * Returns the sender 'ActorRef' of the current message.
    */
@@ -109,10 +99,6 @@ trait ActorContext extends ActorRefFactory {
    */
   implicit def dispatcher: MessageDispatcher
 
-  def handleFailure(child: ActorRef, cause: Throwable): Unit
-
-  def handleChildTerminated(child: ActorRef): Unit
-
   /**
    * The system that the actor belongs to.
    * Importing this member will place a implicit MessageDispatcher in scope.

akka-actor/src/main/scala/akka/actor/ActorRef.scala

@@ -18,34 +18,57 @@ import akka.event.LoggingAdapter
 import java.util.concurrent.atomic.AtomicBoolean
 
 /**
- * ActorRef is an immutable and serializable handle to an Actor.
- * <p/>
- * Create an ActorRef for an Actor by using the factory method on the Actor object.
- * <p/>
- * Here is an example on how to create an actor with a default constructor.
- * <pre>
- *   import Actor._
+ * Immutable and serializable handle to an actor, which may or may not reside
+ * on the local host or inside the same [[akka.actor.ActorSystem]]. An ActorRef
+ * can be obtained from an [[akka.actor.ActorRefFactory]], an interface which
+ * is implemented by ActorSystem and [[akka.actor.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.
  *
- *   val actor = actorOf(Props[MyActor]
- *   actor ! message
- *   actor.stop()
- * </pre>
+ * ActorRefs can be freely shared among actors by message passing. Message
+ * passing conversely is their only purpose, as demonstrated in the following
+ * examples:
  *
- * You can also create and start actors like this:
- * <pre>
- *   val actor = actorOf(Props[MyActor]
- * </pre>
+ * Scala:
+ * {{{
+ * class ExampleActor extends Actor {
+ *   val other = context.actorOf(Props[OtherActor], "childName") // will be destroyed and re-created upon restart by default
  *
- * Here is an example on how to create an actor with a non-default constructor.
- * <pre>
- *   import Actor._
+ *   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) => sender ! (other ? msg)  // will reply with a Future for holding other’s reply (implicit timeout from "akka.actor.timeout")
+ *   }
+ * }
+ * }}}
  *
- *   val actor = actorOf(Props(new MyActor(...))
- *   actor ! message
- *   actor.stop()
- * </pre>
+ * Java:
+ * {{{
+ * public class ExampleActor Extends UntypedActor {
+ *   // this child will be destroyed and re-created upon restart by default
+ *   final ActorRef other = getContext().actorOf(new Props(OtherActor.class), "childName");
  *
- * The natural ordering of ActorRef is defined in terms of its [[akka.actor.ActorPath]].
+ *   @Override
+ *   public void onReceive(Object o) {
+ *     if (o instanceof Request1) {
+ *       val msg = ((Request1) o).getMsg();
+ *       other.tell(msg);              // uses this actor as sender reference, reply goes to us
+ *
+ *     } else if (o instanceof Request2) {
+ *       val msg = ((Request2) o).getMsg();
+ *       other.tell(msg, getSender()); // forward sender reference, enabling direct reply
+ *
+ *     } else if (o instanceof Request3) {
+ *       val msg = ((Request3) o).getMsg();
+ *       getSender().tell(other.ask(msg, 5000)); // reply with Future for holding the other’s reply (timeout 5 seconds)
+ *
+ *     }
+ *   }
+ * }
+ * }}}
+ *
+ * ActorRef does not have a method for terminating the actor it points to, use
+ * [[akka.actor.ActorRefFactory]]`.stop(child)` for this purpose.
  */
 abstract class ActorRef extends java.lang.Comparable[ActorRef] with Serializable {
   scalaRef: InternalActorRef ⇒

akka-actor/src/main/scala/akka/actor/IO.scala

@@ -46,15 +46,15 @@ object IO {
     override def asReadable = this
 
     def read(len: Int)(implicit actor: Actor with IO): ByteString @cps[IOSuspendable[Any]] = shift { cont: (ByteString ⇒ IOSuspendable[Any]) ⇒
-      ByteStringLength(cont, this, actor.context.currentMessage, len)
+      ByteStringLength(cont, this, actor.context.asInstanceOf[ActorCell].currentMessage, len)
     }
 
     def read()(implicit actor: Actor with IO): ByteString @cps[IOSuspendable[Any]] = shift { cont: (ByteString ⇒ IOSuspendable[Any]) ⇒
-      ByteStringAny(cont, this, actor.context.currentMessage)
+      ByteStringAny(cont, this, actor.context.asInstanceOf[ActorCell].currentMessage)
     }
 
     def read(delimiter: ByteString, inclusive: Boolean = false)(implicit actor: Actor with IO): ByteString @cps[IOSuspendable[Any]] = shift { cont: (ByteString ⇒ IOSuspendable[Any]) ⇒
-      ByteStringDelimited(cont, this, actor.context.currentMessage, delimiter, inclusive, 0)
+      ByteStringDelimited(cont, this, actor.context.asInstanceOf[ActorCell].currentMessage, delimiter, inclusive, 0)
     }
   }
 
@@ -158,7 +158,7 @@ trait IO {
       }
       run()
     case msg if _next ne Idle ⇒
-      _messages enqueue context.currentMessage
+      _messages enqueue context.asInstanceOf[ActorCell].currentMessage
     case msg if _receiveIO.isDefinedAt(msg) ⇒
       _next = reset { _receiveIO(msg); Idle }
       run()