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-cluster-sharding/src/test/java/akka/cluster/sharding/ClusterShardingTest.java

@@ -5,6 +5,7 @@
 package akka.cluster.sharding;
 
 import static java.util.concurrent.TimeUnit.SECONDS;
+
 import scala.concurrent.duration.Duration;
 
 import akka.actor.AbstractActor;
@@ -17,13 +18,10 @@ import akka.actor.Props;
 import akka.actor.SupervisorStrategy;
 import akka.actor.Terminated;
 import akka.actor.ReceiveTimeout;
-import akka.actor.UntypedActor;
-import akka.japi.Procedure;
 import akka.japi.Option;
-import akka.persistence.UntypedPersistentActor;
+import akka.persistence.AbstractPersistentActor;
 import akka.cluster.Cluster;
 import akka.japi.pf.DeciderBuilder;
-import akka.japi.pf.ReceiveBuilder;
 
 // Doc code, compile only
 public class ClusterShardingTest {
@@ -96,7 +94,7 @@ public class ClusterShardingTest {
   }
 
   static//#counter-actor
-  public class Counter extends UntypedPersistentActor {
+  public class Counter extends AbstractPersistentActor {
 
     public static enum CounterOp {
       INCREMENT, DECREMENT
@@ -139,7 +137,7 @@ public class ClusterShardingTest {
     @Override
     public void preStart() throws Exception {
       super.preStart();
-      context().setReceiveTimeout(Duration.create(120, SECONDS));
+      getContext().setReceiveTimeout(Duration.create(120, SECONDS));
     }
 
     void updateState(CounterChanged event) {
@@ -147,45 +145,45 @@ public class ClusterShardingTest {
     }
 
     @Override
-    public void onReceiveRecover(Object msg) {
-      if (msg instanceof CounterChanged)
-        updateState((CounterChanged) msg);
-      else
-        unhandled(msg);
+    public Receive createReceiveRecover() {
+      return receiveBuilder()
+          .match(CounterChanged.class, this::updateState)
+          .build();
     }
 
     @Override
-    public void onReceiveCommand(Object msg) {
-      if (msg instanceof Get)
-        getSender().tell(count, getSelf());
-
-      else if (msg == CounterOp.INCREMENT)
-        persist(new CounterChanged(+1), new Procedure<CounterChanged>() {
-          public void apply(CounterChanged evt) {
-            updateState(evt);
-          }
-        });
-
-      else if (msg == CounterOp.DECREMENT)
-        persist(new CounterChanged(-1), new Procedure<CounterChanged>() {
-          public void apply(CounterChanged evt) {
-            updateState(evt);
-          }
-        });
-
-      else if (msg.equals(ReceiveTimeout.getInstance()))
-        getContext().parent().tell(
-            new ShardRegion.Passivate(PoisonPill.getInstance()), getSelf());
-
-      else
-        unhandled(msg);
+    public Receive createReceive() {
+      return receiveBuilder()
+        .match(Get.class, this::receiveGet)
+        .matchEquals(CounterOp.INCREMENT, msg -> receiveIncrement())
+        .matchEquals(CounterOp.DECREMENT, msg -> receiveDecrement())
+        .matchEquals(ReceiveTimeout.getInstance(), msg -> passivate())
+        .build();
     }
+
+    private void receiveGet(Get msg) {
+      getSender().tell(count, getSelf());
+    }
+
+    private void receiveIncrement() {
+      persist(new CounterChanged(+1), this::updateState);
+    }
+
+    private void receiveDecrement() {
+      persist(new CounterChanged(-1), this::updateState);
+    }
+
+    private void passivate() {
+      getContext().parent().tell(
+          new ShardRegion.Passivate(PoisonPill.getInstance()), getSelf());
+    }
+
   }
 
   //#counter-actor
 
   static//#supervisor
-  public class CounterSupervisor extends UntypedActor {
+  public class CounterSupervisor extends AbstractActor {
 
     private final ActorRef counter = getContext().actorOf(
         Props.create(Counter.class), "theCounter");
@@ -203,9 +201,12 @@ public class ClusterShardingTest {
     }
 
     @Override
-    public void onReceive(Object msg) {
-      counter.forward(msg, getContext());
+    public Receive createReceive() {
+      return receiveBuilder()
+        .match(Object.class, msg -> counter.forward(msg, getContext()))
+        .build();
     }
+
   }
   //#supervisor