deprecate closure-taking Props factories, see #3081

- base Props on Deploy, Class and Seq[Any] (i.e. constructor args)
- remove deprecated Props usage from akka-docs sample code
- rewrite UntypedActorDocTestBase
- rewrite Java/Scala doc section on actor creation
- add migration guide entry

akka-docs/rst/java/code/docs/jrouting/ConsistentHashingRouterDocTestBase.java

@@ -66,6 +66,7 @@ public class ConsistentHashingRouterDocTestBase {
   static
   //#cache-actor
   public final class Evict implements Serializable {
+    private static final long serialVersionUID = 1L;
     public final String key;
     public Evict(String key) {
       this.key = key;
@@ -76,6 +77,7 @@ public class ConsistentHashingRouterDocTestBase {
   static
   //#cache-actor
   public final class Get implements Serializable, ConsistentHashable {
+    private static final long serialVersionUID = 1L;
     public final String key;
     public Get(String key) {
       this.key = key;
@@ -89,6 +91,7 @@ public class ConsistentHashingRouterDocTestBase {
   static
   //#cache-actor
   public final class Entry implements Serializable {
+    private static final long serialVersionUID = 1L;
     public final String key;
     public final String value;
     public Entry(String key, String value) {
@@ -122,7 +125,7 @@ public class ConsistentHashingRouterDocTestBase {
         }
       };
 
-      ActorRef cache = system.actorOf(new Props(Cache.class).withRouter(
+      ActorRef cache = system.actorOf(Props.create(Cache.class).withRouter(
         new ConsistentHashingRouter(10).withHashMapper(hashMapper)), 
         "cache");
 

akka-docs/rst/java/code/docs/jrouting/CustomRouterDocTestBase.java

@@ -57,7 +57,7 @@ public class CustomRouterDocTestBase {
   @Test
   public void demonstrateDispatchers() {
     //#dispatchers
-    final ActorRef router = system.actorOf(new Props(MyActor.class)
+    final ActorRef router = system.actorOf(Props.create(MyActor.class)
       // “head” router will run on "head" dispatcher
       .withRouter(new RoundRobinRouter(5).withDispatcher("head"))
       // MyActor “workers” will run on "workers" dispatcher
@@ -71,7 +71,7 @@ public class CustomRouterDocTestBase {
     final SupervisorStrategy strategy =
       new OneForOneStrategy(5, Duration.create("1 minute"),
          Collections.<Class<? extends Throwable>>singletonList(Exception.class));
-    final ActorRef router = system.actorOf(new Props(MyActor.class)
+    final ActorRef router = system.actorOf(Props.create(MyActor.class)
         .withRouter(new RoundRobinRouter(5).withSupervisorStrategy(strategy)));
     //#supervision
   }
@@ -80,7 +80,7 @@ public class CustomRouterDocTestBase {
   @Test
   public void countVotesAsIntendedNotAsInFlorida() throws Exception {
     ActorRef routedActor = system.actorOf(
-      new Props().withRouter(new VoteCountRouter()));
+      Props.empty().withRouter(new VoteCountRouter()));
     routedActor.tell(DemocratVote, null);
     routedActor.tell(DemocratVote, null);
     routedActor.tell(RepublicanVote, null);
@@ -167,9 +167,9 @@ public class CustomRouterDocTestBase {
     @Override
     public CustomRoute createCustomRoute(RouteeProvider routeeProvider) {
       final ActorRef democratActor =
-        routeeProvider.context().actorOf(new Props(DemocratActor.class), "d");
+        routeeProvider.context().actorOf(Props.create(DemocratActor.class), "d");
       final ActorRef republicanActor =
-        routeeProvider.context().actorOf(new Props(RepublicanActor.class), "r");
+        routeeProvider.context().actorOf(Props.create(RepublicanActor.class), "r");
       List<ActorRef> routees =
         Arrays.asList(new ActorRef[] { democratActor, republicanActor });
 

akka-docs/rst/java/code/docs/jrouting/ParentActor.java

@@ -22,7 +22,7 @@ public class ParentActor extends UntypedActor {
     if (msg.equals("rrr")) {
       //#roundRobinRouter
       ActorRef roundRobinRouter = getContext().actorOf(
-          new Props(PrintlnActor.class).withRouter(new RoundRobinRouter(5)),
+          Props.create(PrintlnActor.class).withRouter(new RoundRobinRouter(5)),
         "router");
       for (int i = 1; i <= 10; i++) {
         roundRobinRouter.tell(i, getSelf());
@@ -31,7 +31,7 @@ public class ParentActor extends UntypedActor {
     } else if (msg.equals("rr")) {
       //#randomRouter
       ActorRef randomRouter = getContext().actorOf(
-        new Props(PrintlnActor.class).withRouter(new RandomRouter(5)),
+        Props.create(PrintlnActor.class).withRouter(new RandomRouter(5)),
           "router");
       for (int i = 1; i <= 10; i++) {
         randomRouter.tell(i, getSelf());
@@ -40,7 +40,7 @@ public class ParentActor extends UntypedActor {
     } else if (msg.equals("smr")) {
       //#smallestMailboxRouter
       ActorRef smallestMailboxRouter = getContext().actorOf(
-          new Props(PrintlnActor.class).withRouter(new SmallestMailboxRouter(5)),
+          Props.create(PrintlnActor.class).withRouter(new SmallestMailboxRouter(5)),
         "router");
       for (int i = 1; i <= 10; i++) {
         smallestMailboxRouter.tell(i, getSelf());
@@ -49,13 +49,13 @@ public class ParentActor extends UntypedActor {
     } else if (msg.equals("br")) {
       //#broadcastRouter
       ActorRef broadcastRouter = getContext().actorOf(
-        new Props(PrintlnActor.class).withRouter(new BroadcastRouter(5)), "router");
+        Props.create(PrintlnActor.class).withRouter(new BroadcastRouter(5)), "router");
       broadcastRouter.tell("this is a broadcast message", getSelf());
       //#broadcastRouter
     } else if (msg.equals("sgfcr")) {
       //#scatterGatherFirstCompletedRouter
       ActorRef scatterGatherFirstCompletedRouter = getContext().actorOf(
-          new Props(FibonacciActor.class).withRouter(
+          Props.create(FibonacciActor.class).withRouter(
             new ScatterGatherFirstCompletedRouter(5, Duration.create(2, "seconds"))),
         "router");
       Timeout timeout = new Timeout(Duration.create(5, "seconds"));

akka-docs/rst/java/code/docs/jrouting/RouterViaConfigExample.java

@@ -44,7 +44,7 @@ public class RouterViaConfigExample {
     ActorSystem system = ActorSystem.create("Example", config);
     //#configurableRouting
     ActorRef router = system.actorOf(
-      new Props(ExampleActor.class).withRouter(new FromConfig()), "myrouter1");
+      Props.create(ExampleActor.class).withRouter(new FromConfig()), "myrouter1");
     //#configurableRouting
     for (int i = 1; i <= 10; i++) {
       router.tell(new ExampleActor.Message(i), null);
@@ -52,7 +52,7 @@ public class RouterViaConfigExample {
 
     //#configurableRoutingWithResizer
     ActorRef router2 = system.actorOf(
-      new Props(ExampleActor.class).withRouter(new FromConfig()), "myrouter2");
+      Props.create(ExampleActor.class).withRouter(new FromConfig()), "myrouter2");
     //#configurableRoutingWithResizer
     for (int i = 1; i <= 10; i++) {
       router2.tell(new ExampleActor.Message(i), null);

akka-docs/rst/java/code/docs/jrouting/RouterViaProgramDocTestBase.java

@@ -3,21 +3,23 @@
  */
 package docs.jrouting;
 
-import akka.actor.*;
-import akka.remote.routing.RemoteRouterConfig;
+import java.util.Arrays;
+
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+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.routing.Broadcast;
 import akka.routing.RoundRobinRouter;
 import akka.testkit.JavaTestKit;
 import docs.jrouting.RouterViaProgramExample.ExampleActor;
 import docs.routing.RouterViaProgramDocSpec.Echo;
-import java.io.Serializable;
-import java.util.Arrays;
-import java.util.HashMap;
-import java.util.Map;
-import org.junit.AfterClass;
-import org.junit.Assert;
-import org.junit.BeforeClass;
-import org.junit.Test;
 
 public class RouterViaProgramDocTestBase {
 
@@ -45,17 +47,18 @@ public class RouterViaProgramDocTestBase {
     }
   }
 
+  @SuppressWarnings("unused")
   @Test
   public void demonstrateRouteesFromPaths() {
     new JavaTestKit(system) {{
       //#programmaticRoutingRouteePaths      
-      ActorRef actor1 = system.actorOf(new Props(ExampleActor.class), "actor1");
-      ActorRef actor2 = system.actorOf(new Props(ExampleActor.class), "actor2");
-      ActorRef actor3 = system.actorOf(new Props(ExampleActor.class), "actor3");
+      ActorRef actor1 = system.actorOf(Props.create(ExampleActor.class), "actor1");
+      ActorRef actor2 = system.actorOf(Props.create(ExampleActor.class), "actor2");
+      ActorRef actor3 = system.actorOf(Props.create(ExampleActor.class), "actor3");
       Iterable<String> routees = Arrays.asList(
         new String[] { "/user/actor1", "/user/actor2", "/user/actor3" });
       ActorRef router = system.actorOf(
-        new Props().withRouter(new RoundRobinRouter(routees)));
+        Props.empty().withRouter(new RoundRobinRouter(routees)));
       //#programmaticRoutingRouteePaths
       for (int i = 1; i <= 6; i++) {
         router.tell(new ExampleActor.Message(i), null);
@@ -66,7 +69,7 @@ public class RouterViaProgramDocTestBase {
   @Test
   public void demonstrateBroadcast() {
     new JavaTestKitWithSelf(system) {{
-      ActorRef router = system.actorOf(new Props(Echo.class).withRouter(new RoundRobinRouter(5)));
+      ActorRef router = system.actorOf(Props.create(Echo.class).withRouter(new RoundRobinRouter(5)));
       //#broadcastDavyJonesWarning
       router.tell(new Broadcast("Watch out for Davy Jones' locker"), getSelf());
       //#broadcastDavyJonesWarning
@@ -77,7 +80,7 @@ public class RouterViaProgramDocTestBase {
   @Test
   public void demonstratePoisonPill() {
     new JavaTestKitWithSelf(system) {{
-      ActorRef router = system.actorOf(new Props(Echo.class).withRouter(new RoundRobinRouter(5)));
+      ActorRef router = system.actorOf(Props.create(Echo.class).withRouter(new RoundRobinRouter(5)));
       watch(router);
       //#poisonPill
       router.tell(PoisonPill.getInstance(), getSelf());
@@ -89,7 +92,7 @@ public class RouterViaProgramDocTestBase {
   @Test
   public void demonstrateBroadcastOfPoisonPill() {
     new JavaTestKitWithSelf(system) {{
-      ActorRef router = system.actorOf(new Props(Echo.class).withRouter(new RoundRobinRouter(5)));
+      ActorRef router = system.actorOf(Props.create(Echo.class).withRouter(new RoundRobinRouter(5)));
       watch(router);
       //#broadcastPoisonPill
       router.tell(new Broadcast(PoisonPill.getInstance()), getSelf());
@@ -101,7 +104,7 @@ public class RouterViaProgramDocTestBase {
   @Test
   public void demonstrateKill() {
     new JavaTestKitWithSelf(system) {{
-      ActorRef router = system.actorOf(new Props(Echo.class).withRouter(new RoundRobinRouter(5)));
+      ActorRef router = system.actorOf(Props.create(Echo.class).withRouter(new RoundRobinRouter(5)));
       watch(router);
       //#kill
       router.tell(Kill.getInstance(), getSelf());
@@ -113,7 +116,7 @@ public class RouterViaProgramDocTestBase {
   @Test
   public void demonstrateBroadcastOfKill() {
     new JavaTestKitWithSelf(system) {{
-      ActorRef router = system.actorOf(new Props(Echo.class).withRouter(new RoundRobinRouter(5)));
+      ActorRef router = system.actorOf(Props.create(Echo.class).withRouter(new RoundRobinRouter(5)));
       watch(router);
       //#broadcastKill
       router.tell(new Broadcast(Kill.getInstance()), getSelf());

akka-docs/rst/java/code/docs/jrouting/RouterViaProgramExample.java

@@ -41,25 +41,26 @@ public class RouterViaProgramExample {
     }
   }
 
+  @SuppressWarnings("unused")
   public static void main(String... args) {
     ActorSystem system = ActorSystem.create("RPE");
     //#programmaticRoutingNrOfInstances
     int nrOfInstances = 5;
     ActorRef router1 = system.actorOf(
-      new Props(ExampleActor.class).withRouter(new RoundRobinRouter(nrOfInstances)));
+      Props.create(ExampleActor.class).withRouter(new RoundRobinRouter(nrOfInstances)));
     //#programmaticRoutingNrOfInstances
     for (int i = 1; i <= 6; i++) {
       router1.tell(new ExampleActor.Message(i), null);
     }
 
     //#programmaticRoutingRoutees
-    ActorRef actor1 = system.actorOf(new Props(ExampleActor.class));
-    ActorRef actor2 = system.actorOf(new Props(ExampleActor.class));
-    ActorRef actor3 = system.actorOf(new Props(ExampleActor.class));
+    ActorRef actor1 = system.actorOf(Props.create(ExampleActor.class));
+    ActorRef actor2 = system.actorOf(Props.create(ExampleActor.class));
+    ActorRef actor3 = system.actorOf(Props.create(ExampleActor.class));
     Iterable<ActorRef> routees = Arrays.asList(
       new ActorRef[] { actor1, actor2, actor3 });
     ActorRef router2 = system.actorOf(
-      new Props().withRouter(RoundRobinRouter.create(routees)));
+      Props.empty().withRouter(RoundRobinRouter.create(routees)));
     //#programmaticRoutingRoutees
     for (int i = 1; i <= 6; i++) {
       router2.tell(new ExampleActor.Message(i), null);
@@ -70,7 +71,7 @@ public class RouterViaProgramExample {
     int upperBound = 15;
     DefaultResizer resizer = new DefaultResizer(lowerBound, upperBound);
     ActorRef router3 = system.actorOf(
-      new Props(ExampleActor.class).withRouter(new RoundRobinRouter(resizer)));
+      Props.create(ExampleActor.class).withRouter(new RoundRobinRouter(resizer)));
     //#programmaticRoutingWithResizer
     for (int i = 1; i <= 6; i++) {
       router3.tell(new ExampleActor.Message(i), null);
@@ -80,11 +81,12 @@ public class RouterViaProgramExample {
     Address addr1 = new Address("akka", "remotesys", "otherhost", 1234);
     Address addr2 = AddressFromURIString.parse("akka://othersys@anotherhost:1234");
     Address[] addresses = new Address[] { addr1, addr2 };
-    ActorRef routerRemote = system.actorOf(new Props(ExampleActor.class)
+    ActorRef routerRemote = system.actorOf(Props.create(ExampleActor.class)
       .withRouter(new RemoteRouterConfig(new RoundRobinRouter(5), addresses)));
     //#remoteRoutees
   }
   
+  @SuppressWarnings("unused")
   private class CompileCheckJavaDocsForRouting extends UntypedActor {
 
     @Override