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/io/japi/SimpleEchoHandler.java

@@ -9,7 +9,7 @@ import java.util.LinkedList;
 import java.util.Queue;
 
 import akka.actor.ActorRef;
-import akka.actor.UntypedActor;
+import akka.actor.AbstractActor;
 import akka.event.Logging;
 import akka.event.LoggingAdapter;
 import akka.io.Tcp.ConnectionClosed;
@@ -20,10 +20,10 @@ import akka.japi.Procedure;
 import akka.util.ByteString;
 
 //#simple-echo-handler
-public class SimpleEchoHandler extends UntypedActor {
+public class SimpleEchoHandler extends AbstractActor {
   
   final LoggingAdapter log = Logging
-      .getLogger(getContext().system(), getSelf());
+      .getLogger(getContext().system(), self());
 
   final ActorRef connection;
   final InetSocketAddress remote;
@@ -41,38 +41,42 @@ public class SimpleEchoHandler extends UntypedActor {
   }
 
   @Override
-  public void onReceive(Object msg) throws Exception {
-    if (msg instanceof Received) {
-      final ByteString data = ((Received) msg).data();
-      buffer(data);
-      connection.tell(TcpMessage.write(data, ACK), getSelf());
-      // now switch behavior to “waiting for acknowledgement”
-      getContext().become(buffering, false);
-
-    } else if (msg instanceof ConnectionClosed) {
-      getContext().stop(getSelf());
-    }
+  public Receive createReceive() {
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        final ByteString data = msg.data();
+        buffer(data);
+        connection.tell(TcpMessage.write(data, ACK), self());
+        // now switch behavior to “waiting for acknowledgement”
+        getContext().become(buffering(), false);
+  
+      })
+      .match(ConnectionClosed.class, msg -> {
+        getContext().stop(self());
+      })
+      .build();
   }
 
-  private final Procedure<Object> buffering = new Procedure<Object>() {
-    @Override
-    public void apply(Object msg) throws Exception {
-      if (msg instanceof Received) {
-        buffer(((Received) msg).data());
+  private final Receive buffering() {
+    return receiveBuilder()
+      .match(Received.class, msg -> {
+        buffer(msg.data());
         
-      } else if (msg == ACK) {
+      })
+      .match(Event.class, msg -> msg == ACK, msg -> {
         acknowledge();
 
-      } else if (msg instanceof ConnectionClosed) {
-        if (((ConnectionClosed) msg).isPeerClosed()) {
+      })
+      .match(ConnectionClosed.class, msg -> {
+        if (msg.isPeerClosed()) {
           closing = true;
         } else {
           // could also be ErrorClosed, in which case we just give up
-          getContext().stop(getSelf());
+          getContext().stop(self());
         }
-      }
-    }
-  };
+      })
+      .build();
+  }
 
   //#storage-omitted
   public void postStop() {
@@ -95,11 +99,11 @@ public class SimpleEchoHandler extends UntypedActor {
 
     if (stored > maxStored) {
       log.warning("drop connection to [{}] (buffer overrun)", remote);
-      getContext().stop(getSelf());
+      getContext().stop(self());
 
     } else if (stored > highWatermark) {
       log.debug("suspending reading");
-      connection.tell(TcpMessage.suspendReading(), getSelf());
+      connection.tell(TcpMessage.suspendReading(), self());
       suspended = true;
     }
   }
@@ -111,18 +115,18 @@ public class SimpleEchoHandler extends UntypedActor {
 
     if (suspended && stored < lowWatermark) {
       log.debug("resuming reading");
-      connection.tell(TcpMessage.resumeReading(), getSelf());
+      connection.tell(TcpMessage.resumeReading(), self());
       suspended = false;
     }
     
     if (storage.isEmpty()) {
       if (closing) {
-        getContext().stop(getSelf());
+        getContext().stop(self());
       } else {
         getContext().unbecome();
       }
     } else {
-      connection.tell(TcpMessage.write(storage.peek(), ACK), getSelf());
+      connection.tell(TcpMessage.write(storage.peek(), ACK), self());
     }
   }
   //#simple-helpers