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/java/code/docs/testkit/TestKitDocTest.java

@@ -16,6 +16,7 @@ import akka.actor.ActorKilledException;
 import akka.actor.ActorRef;
 import akka.actor.ActorSystem;
 import akka.actor.Kill;
+import akka.actor.PoisonPill;
 import akka.actor.Props;
 import akka.actor.Terminated;
 import akka.actor.UntypedActor;
@@ -30,7 +31,7 @@ import akka.testkit.JavaTestKit;
 import scala.concurrent.duration.Duration;
 
 public class TestKitDocTest {
-  
+
   //#test-actor-ref
   static class MyActor extends UntypedActor {
     public void onReceive(Object o) throws Exception {
@@ -42,18 +43,18 @@ public class TestKitDocTest {
     }
     public boolean testMe() { return true; }
   }
-  
+
   //#test-actor-ref
-  
+
   private static ActorSystem system;
-  
+
   @BeforeClass
   public static void setup() {
     final Config config = ConfigFactory.parseString(
         "akka.loggers = [akka.testkit.TestEventListener]");
     system = ActorSystem.create("demoSystem", config);
   }
-  
+
   @AfterClass
   public static void cleanup() {
     system.shutdown();
@@ -68,7 +69,7 @@ public class TestKitDocTest {
     assertTrue(actor.testMe());
   }
   //#test-actor-ref
-  
+
   @Test
   public void demonstrateAsk() throws Exception {
     //#test-behavior
@@ -79,7 +80,7 @@ public class TestKitDocTest {
     assertEquals(42, Await.result(future, Duration.Zero()));
     //#test-behavior
   }
-  
+
   @Test
   public void demonstrateExceptions() {
     //#test-expecting-exceptions
@@ -93,7 +94,7 @@ public class TestKitDocTest {
     }
     //#test-expecting-exceptions
   }
-  
+
   @Test
   public void demonstrateWithin() {
     //#test-within
@@ -108,7 +109,7 @@ public class TestKitDocTest {
     }};
     //#test-within
   }
-  
+
   @Test
   public void demonstrateExpectMsg() {
     //#test-expectmsg
@@ -128,7 +129,7 @@ public class TestKitDocTest {
     }};
     //#test-expectmsg
   }
-  
+
   @Test
   public void demonstrateReceiveWhile() {
     //#test-receivewhile
@@ -136,7 +137,7 @@ public class TestKitDocTest {
       getRef().tell(42, null);
       getRef().tell(43, null);
       getRef().tell("hello", null);
-      final String[] out = 
+      final String[] out =
         new ReceiveWhile<String>(String.class, duration("1 second")) {
           // do not put code outside this method, will run afterwards
           protected String match(Object in) {
@@ -168,7 +169,7 @@ public class TestKitDocTest {
       //#test-receivewhile-full
     }};
   }
-  
+
   @Test
   public void demonstrateAwaitCond() {
     //#test-awaitCond
@@ -205,7 +206,7 @@ public class TestKitDocTest {
     }};
     //#test-awaitAssert
   }
-  
+
   @Test
   @SuppressWarnings("unchecked") // due to generic varargs
   public void demonstrateExpect() {
@@ -236,7 +237,7 @@ public class TestKitDocTest {
       assertArrayEquals(new String[] {"hello", "world"}, all);
     }};
   }
-  
+
   @Test
   public void demonstrateIgnoreMsg() {
     //#test-ignoreMsg
@@ -268,7 +269,7 @@ public class TestKitDocTest {
     }};
     //#duration-dilation
   }
-  
+
   @Test
   public void demonstrateProbe() {
     //#test-probe
@@ -282,11 +283,11 @@ public class TestKitDocTest {
         target.forward(msg, getContext());
       }
     }
-    
+
     new JavaTestKit(system) {{
       // create a test probe
       final JavaTestKit probe = new JavaTestKit(system);
-      
+
       // create a forwarder, injecting the probe’s testActor
       final Props props = new Props(new UntypedActorFactory() {
         private static final long serialVersionUID = 8927158735963950216L;
@@ -295,7 +296,7 @@ public class TestKitDocTest {
         }
       });
       final ActorRef forwarder = system.actorOf(props, "forwarder");
-      
+
       // verify correct forwarding
       forwarder.tell(42, getRef());
       probe.expectMsgEquals(42);
@@ -303,7 +304,7 @@ public class TestKitDocTest {
     }};
     //#test-probe
   }
-  
+
   @Test
   public void demonstrateSpecialProbe() {
     //#test-special-probe
@@ -323,20 +324,21 @@ public class TestKitDocTest {
     }};
     //#test-special-probe
   }
-  
+
   @Test
   public void demonstrateWatch() {
-    final ActorRef target = system.actorFor("/buh");
+    final ActorRef target = system.actorOf(new Props(MyActor.class));
     //#test-probe-watch
     new JavaTestKit(system) {{
       final JavaTestKit probe = new JavaTestKit(system);
       probe.watch(target);
+      target.tell(PoisonPill.getInstance(), null);
       final Terminated msg = probe.expectMsgClass(Terminated.class);
       assertEquals(msg.getActor(), target);
     }};
     //#test-probe-watch
   }
-  
+
   @Test
   public void demonstrateReply() {
     //#test-probe-reply
@@ -350,7 +352,7 @@ public class TestKitDocTest {
     }};
     //#test-probe-reply
   }
-  
+
   @Test
   public void demonstrateForward() {
     //#test-probe-forward
@@ -364,7 +366,7 @@ public class TestKitDocTest {
     }};
     //#test-probe-forward
   }
-  
+
   @Test
   public void demonstrateWithinProbe() {
     try {
@@ -382,7 +384,7 @@ public class TestKitDocTest {
       // expected to fail
     }
   }
-  
+
   @Test
   public void demonstrateAutoPilot() {
     //#test-auto-pilot
@@ -404,7 +406,7 @@ public class TestKitDocTest {
     }};
     //#test-auto-pilot
   }
-  
+
   // only compilation
   public void demonstrateCTD() {
     //#calling-thread-dispatcher
@@ -413,24 +415,24 @@ public class TestKitDocTest {
         .withDispatcher(CallingThreadDispatcher.Id()));
     //#calling-thread-dispatcher
   }
-  
+
   @Test
   public void demonstrateEventFilter() {
     //#test-event-filter
     new JavaTestKit(system) {{
       assertEquals("demoSystem", system.name());
       final ActorRef victim = system.actorOf(Props.empty(), "victim");
-      
+
       final int result = new EventFilter<Integer>(ActorKilledException.class) {
         protected Integer run() {
           victim.tell(Kill.getInstance(), null);
           return 42;
         }
       }.from("akka://demoSystem/user/victim").occurrences(1).exec();
-      
+
       assertEquals(42, result);
     }};
     //#test-event-filter
   }
-  
+
 }