Adding create() to ReceiveBuilder to promote a builder-like syntax #18894

akka-actor/src/main/java/akka/japi/pf/ReceiveBuilder.java

@@ -36,6 +36,16 @@ public class ReceiveBuilder {
   private ReceiveBuilder() {
   }
 
+  /**
+   * Return a new {@link UnitPFBuilder} with no case statements. They can be added later as the returned {@link
+   * UnitPFBuilder} is a mutable object.
+   *
+   * @return a builder with no case statements
+   */
+  public static UnitPFBuilder<Object> create() {
+    return new UnitPFBuilder<>();
+  }
+
   /**
    * Return a new {@link UnitPFBuilder} with a case statement added.
    *

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

@@ -365,6 +365,22 @@ public class ActorDocTest extends AbstractJavaTest {
     }
   }
 
+  @Test
+  public void creatingGraduallyBuiltActorWithSystemActorOf() {
+    final ActorSystem system = ActorSystem.create("MySystem", config);
+    final ActorRef actor = system.actorOf(Props.create(GraduallyBuiltActor.class), "graduallyBuiltActor");
+    try {
+      new JavaTestKit(system) {
+        {
+          actor.tell("hello", getRef());
+          expectMsgEquals("hello");
+        }
+      };
+    } finally {
+      JavaTestKit.shutdownActorSystem(system);
+    }
+  }
+
   @Test
   public void creatingPropsConfig() {
     //#creating-props

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

@@ -0,0 +1,35 @@
+/**
+ * Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package docs.actorlambda;
+
+//#imports
+import akka.actor.AbstractActor;
+import akka.event.Logging;
+import akka.event.LoggingAdapter;
+import akka.japi.pf.ReceiveBuilder;
+import akka.japi.pf.UnitPFBuilder;
+
+//#imports
+
+//#actor
+public class GraduallyBuiltActor extends AbstractActor {
+  private final LoggingAdapter log = Logging.getLogger(context().system(), this);
+
+  public GraduallyBuiltActor() {
+    UnitPFBuilder<Object> builder = ReceiveBuilder.create();
+    builder.match(String.class, s -> {
+      log.info("Received String message: {}", s);
+      //#actor
+      //#reply
+      sender().tell(s, self());
+      //#reply
+      //#actor
+    });
+    // do some other stuff in between
+    builder.matchAny(o -> log.info("received unknown message"));
+    receive(builder.build());
+  }
+}
+//#actor

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

@@ -54,6 +54,12 @@ Here is an example:
 .. includecode:: code/docs/actorlambda/MyActor.java
    :include: imports,my-actor
 
+In case you want to provide many :meth:`match` cases but want to avoid creating a long call
+trail, you can split the creation of the builder into multiple statements as in the example:
+
+.. includecode:: code/docs/actorlambda/GraduallyBuiltActor.java
+   :include: imports,actor
+
 Please note that the Akka Actor ``receive`` message loop is exhaustive, which
 is different compared to Erlang and the late Scala Actors. This means that you
 need to provide a pattern match for all messages that it can accept and if you