improve AbstractActor, #21717

* Receive class that wraps PartialFunction, to avoid
  scary scala types
* move AbstractActorContext to AbstractActor.ActorContext
* converting docs, many, many UntypedActor
* removing UntypedActor docs
* add unit test for ReceiveBuilder
* MiMa filters
* consistent use of getContext(), self(), sender()
* rename cross references
* migration guide
* skip samples for now
* improve match type safetyi, add matchUnchecked
  * the `? extends P` caused code like this to compile:
    `match(String.class, (Integer i) -> {})`
  * added matchUnchecked, since it can still be useful (um, convenient)
    to be able to do:
    `matchUnchecked(List.class, (List<String> list) -> {})`
* eleminate some scala.Option
  * preRestart
  * findChild
  * ActorIdentity.getActorRef

akka-docs/rst/java/code/docs/actorlambda/InitializationDocTest.java

@@ -8,7 +8,6 @@ import akka.actor.ActorRef;
 import akka.actor.ActorSystem;
 import akka.actor.Props;
 import akka.japi.pf.FI;
-import akka.japi.pf.ReceiveBuilder;
 import akka.testkit.JavaTestKit;
 import docs.AbstractJavaTest;
 import org.junit.AfterClass;
@@ -16,7 +15,7 @@ import org.junit.BeforeClass;
 import org.junit.Test;
 import scala.concurrent.Await;
 import scala.concurrent.duration.Duration;
-
+import java.util.Optional;
 import java.util.concurrent.TimeUnit;
 
 public class InitializationDocTest extends AbstractJavaTest {
@@ -32,24 +31,57 @@ public class InitializationDocTest extends AbstractJavaTest {
   public static void afterClass() throws Exception {
     Await.ready(system.terminate(), Duration.create("5 seconds"));
   }
+  
+  static public class PreStartInitExample extends AbstractActor {
+
+    @Override
+    public Receive createReceive() {
+      return AbstractActor.emptyBehavior();
+    }
+
+    //#preStartInit
+    @Override
+    public void preStart() {
+      // Initialize children here
+    }
+
+    // Overriding postRestart to disable the call to preStart()
+    // after restarts
+    @Override
+    public void postRestart(Throwable reason) {
+    }
+
+    // The default implementation of preRestart() stops all the children
+    // of the actor. To opt-out from stopping the children, we
+    // have to override preRestart()
+    @Override
+    public void preRestart(Throwable reason, Optional<Object> message)
+      throws Exception {
+      // Keep the call to postStop(), but no stopping of children
+      postStop();
+    }
+    //#preStartInit
+
+  }
 
   public static class MessageInitExample extends AbstractActor {
     private String initializeMe = null;
 
-    public MessageInitExample() {
-      //#messageInit
-      receive(ReceiveBuilder.
-          matchEquals("init", m1 -> {
-            initializeMe = "Up and running";
-            context().become(ReceiveBuilder.
-              matchEquals("U OK?", m2 -> {
-                sender().tell(initializeMe, self());
-              }).build());
-
-          }).build()
-        //#messageInit
-      );
+    //#messageInit
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchEquals("init", m1 -> {
+          initializeMe = "Up and running";
+          getContext().become(receiveBuilder()
+            .matchEquals("U OK?", m2 -> {
+              sender().tell(initializeMe, self());
+            })
+            .build());
+        })
+        .build();
     }
+    //#messageInit
   }
 
   public class GenericMessage<T> {
@@ -61,24 +93,27 @@ public class InitializationDocTest extends AbstractJavaTest {
   }
 
   public static class GenericActor extends AbstractActor {
-    public GenericActor() {
-      receive(ReceiveBuilder.match(GenericMessage.class, (GenericMessage<String> msg) -> {
-        GenericMessage<String> message = msg;
-        sender().tell(message.value.toUpperCase(), self());
-
-      }).build());
-
-
+    @Override
+    public Receive createReceive() {
+      return receiveBuilder()
+        .matchUnchecked(GenericMessage.class, (GenericMessage<String> msg) -> {
+          GenericMessage<String> message = msg;
+          sender().tell(message.value.toUpperCase(), self());
+        })
+        .build();
     }
   }
 
   static class GenericActorWithPredicate extends AbstractActor {
-    public GenericActorWithPredicate() {
+    @Override
+    public Receive createReceive() {
       FI.TypedPredicate<GenericMessage<String>> typedPredicate = s -> !s.value.isEmpty();
 
-      receive(ReceiveBuilder.match(GenericMessage.class, typedPredicate, (GenericMessage<String> msg) -> {
-        sender().tell(msg.value.toUpperCase(), self());
-      }).build());
+      return receiveBuilder()
+        .matchUnchecked(GenericMessage.class, typedPredicate, (GenericMessage<String> msg) -> {
+          sender().tell(msg.value.toUpperCase(), self());
+        })
+        .build();
     }
   }