Deprecate actorFor in favor of ActorSelection, see #3074

* Deprecate all actorFor methods
* resolveActorRef in provider
* Identify auto receive message
* Support ActorPath in actorSelection
* Support remote actor selections
* Additional tests of actor selection
* Update tests (keep most actorFor tests)
* Update samples to use actorSelection
* Updates to documentation
* Migration guide, including motivation

akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala

@@ -327,6 +327,37 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     expectMsg("finished")
   }
 
+  "using Identify" in {
+    //#identify
+    import akka.actor.{ Actor, Props, Identify, ActorIdentity, Terminated }
+
+    class Follower extends Actor {
+      val identifyId = 1
+      context.actorSelection("/user/another") ! Identify(identifyId)
+
+      def receive = {
+        case ActorIdentity(`identifyId`, Some(ref)) ⇒
+          context.watch(ref)
+          context.become(active(ref))
+        case ActorIdentity(`identifyId`, None) ⇒ context.stop(self)
+
+      }
+
+      def active(another: ActorRef): Actor.Receive = {
+        case Terminated(`another`) ⇒ context.stop(self)
+      }
+    }
+    //#identify
+
+    val a = system.actorOf(Props(new Actor {
+      def receive = Actor.emptyBehavior
+    }))
+    val b = system.actorOf(Props(new Follower))
+    watch(b)
+    system.stop(a)
+    expectMsgType[akka.actor.Terminated].actor must be === b
+  }
+
   "using pattern gracefulStop" in {
     val actorRef = system.actorOf(Props[MyActor])
     //#gracefulStop
@@ -386,9 +417,9 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     lastSender must be === actor
     actor ! me
     expectMsg("reply")
-    lastSender must be === system.actorFor("/user")
+    lastSender.path.elements.mkString("/", "/", "") must be === "/user"
     expectMsg("reply")
-    lastSender must be === system.actorFor("/user")
+    lastSender.path.elements.mkString("/", "/", "") must be === "/user"
   }
 
   "using ActorDSL outside of akka.actor package" in {

akka-docs/rst/scala/code/docs/actor/TypedActorDocSpec.scala

@@ -4,17 +4,15 @@
 package docs.actor
 
 import language.postfixOps
-
-//#imports
 import scala.concurrent.{ Promise, Future, Await }
 import scala.concurrent.duration._
 import akka.actor.{ ActorContext, TypedActor, TypedProps }
-
-//#imports
-
 import org.scalatest.{ BeforeAndAfterAll, WordSpec }
 import org.scalatest.matchers.MustMatchers
 import akka.testkit._
+//#typed-actor-impl
+import java.lang.String.{ valueOf ⇒ println } //Mr funny man avoids printing to stdout AND keeping docs alright
+import akka.actor.ActorRef
 
 //#typed-actor-iface
 trait Squarer {
@@ -46,8 +44,6 @@ class SquarerImpl(val name: String) extends Squarer {
   def squareNow(i: Int): Int = i * i
   //#typed-actor-impl-methods
 }
-//#typed-actor-impl
-import java.lang.String.{ valueOf ⇒ println } //Mr funny man avoids printing to stdout AND keeping docs alright
 //#typed-actor-supercharge
 trait Foo {
   def doFoo(times: Int): Unit = println("doFoo(" + times + ")")
@@ -145,12 +141,13 @@ class TypedActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
   }
 
   "proxy any ActorRef" in {
+    val actorRefToRemoteActor: ActorRef = system.deadLetters
     //#typed-actor-remote
     val typedActor: Foo with Bar =
       TypedActor(system).
         typedActorOf(
           TypedProps[FooBar],
-          system.actorFor("akka://SomeSystem@somehost:2552/user/some/foobar"))
+          actorRefToRemoteActor)
     //Use "typedActor" as a FooBar
     //#typed-actor-remote
   }