improve safety of Props.create by allowing Creator<T>, see #3377

Props constructors need to be deprecated instead of being mutated
because we cannot just start throwing exceptions in people’s existing
code. Props.withCreator is deprecated for similar reasons, but also
because Props are about the creators, so replacing that after the fact
is not good style.

akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java

@@ -49,6 +49,7 @@ import akka.actor.IndirectActorProducer;
 import akka.actor.OneForOneStrategy;
 //#import-props
 import akka.actor.Props;
+import akka.japi.Creator;
 //#import-props
 import akka.actor.SupervisorStrategy;
 import akka.actor.SupervisorStrategy.Directive;
@@ -88,14 +89,35 @@ public class UntypedActorDocTest {
 
   private final ActorSystem system = actorSystemResource.getSystem();
 
+  //#creating-props-config
+  static class MyActorC implements Creator<MyActor> {
+    @Override public MyActor create() {
+      return new MyActor("...");
+    }
+  }
+  
+  //#creating-props-config
+
   @SuppressWarnings("unused")
   @Test
   public void createProps() {
     //#creating-props-config
     Props props1 = Props.create(MyUntypedActor.class);
     Props props2 = Props.create(MyActor.class, "...");
+    Props props3 = Props.create(new MyActorC());
     //#creating-props-config
   }
+  
+  //#parametric-creator
+  static class ParametricCreator<T extends MyActor> implements Creator<T> {
+    @Override public T create() {
+      // ... fabricate actor here
+      //#parametric-creator
+      return null;
+      //#parametric-creator
+    }
+  }
+  //#parametric-creator
 
   @SuppressWarnings("deprecation")
   @Test

akka-docs/rst/java/untyped-actors.rst

@@ -51,12 +51,20 @@ dispatcher to use, see more below). Here are some examples of how to create a
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#import-props
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#creating-props-config
 
-The last line shows how to pass constructor arguments to the :class:`Actor`
+The second line shows how to pass constructor arguments to the :class:`Actor`
 being created. The presence of a matching constructor is verified during
 construction of the :class:`Props` object, resulting in an
 :class:`IllegalArgumentEception` if no or multiple matching constructors are
 found.
 
+The third line demonstrates the use of a :class:`Creator<T extends Actor>`. The
+creator class must be static, which is verified during :class:`Props`
+construction. The type parameter’s upper bound is used to determine the
+produced actor class, falling back to :class:`Actor` if fully erased. An
+example of a parametric factory could be:
+
+.. includecode:: code/docs/actor/UntypedActorDocTest.java#parametric-creator
+
 Deprecated Variants
 ^^^^^^^^^^^^^^^^^^^