populate Creating Actors section in the akka typed documentation (#25218) (#25236)

* populate Creating Actors section in the akka typed documentation (#25218)

akka-actor-typed-tests/src/test/java/akka/actor/typed/DispatcherSelectorTest.java

@@ -4,10 +4,6 @@
 
 package akka.actor.typed;
 
-import scala.concurrent.ExecutionContext;
-
-import java.util.concurrent.Executor;
-
 public class DispatcherSelectorTest {
   // Compile time only test to verify
   // dispatcher factories are accessible from Java

akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java

@@ -10,6 +10,8 @@ import akka.actor.typed.ActorRef;
 import akka.actor.typed.ActorSystem;
 import akka.actor.typed.Behavior;
 import akka.actor.typed.Terminated;
+import akka.actor.typed.Props;
+import akka.actor.typed.DispatcherSelector;
 import akka.actor.typed.javadsl.Behaviors;
 
 //#imports
@@ -104,6 +106,37 @@ public class IntroTest {
   }
   //#hello-world-main
 
+  public abstract static class CustomDispatchersExample {
+    private CustomDispatchersExample() {
+    }
+
+    public static class Start {
+      public final String name;
+
+      public Start(String name) {
+        this.name = name;
+      }
+    }
+
+    //#hello-world-main-with-dispatchers
+    public static final Behavior<Start> main =
+      Behaviors.setup( context -> {
+        final String dispatcherPath = "akka.actor.default-blocking-io-dispatcher";
+
+        Props props = DispatcherSelector.fromConfig(dispatcherPath);
+        final ActorRef<HelloWorld.Greet> greeter =
+            context.spawn(HelloWorld.greeter, "greeter", props);
+
+        return Behaviors.receiveMessage(msg -> {
+          ActorRef<HelloWorld.Greeted> replyTo =
+              context.spawn(HelloWorldBot.bot(0, 3), msg.name);
+          greeter.tell(new HelloWorld.Greet(msg.name, replyTo));
+          return Behaviors.same();
+        });
+      });
+    //#hello-world-main-with-dispatchers
+  }
+
   public static void main(String[] args) throws Exception {
     //#hello-world
     final ActorSystem<HelloWorldMain.Start> system =

akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala

@@ -7,7 +7,7 @@ package docs.akka.typed
 //#imports
 import akka.NotUsed
 import akka.actor.typed.scaladsl.Behaviors
-import akka.actor.typed.{ ActorRef, ActorSystem, Behavior, Terminated }
+import akka.actor.typed.{ ActorRef, ActorSystem, Behavior, DispatcherSelector, Terminated }
 //#imports
 
 import akka.actor.testkit.typed.scaladsl.ActorTestKit
@@ -68,6 +68,27 @@ object IntroSpec {
   }
   //#hello-world-main
 
+  object CustomDispatchersExample {
+    import HelloWorldMain.Start
+
+    //#hello-world-main-with-dispatchers
+    val main: Behavior[Start] =
+      Behaviors.setup { context ⇒
+        val dispatcherPath = "akka.actor.default-blocking-io-dispatcher"
+
+        val props = DispatcherSelector.fromConfig(dispatcherPath)
+        val greeter = context.spawn(HelloWorld.greeter, "greeter", props)
+
+        Behaviors.receiveMessage { msg ⇒
+          val replyTo = context.spawn(HelloWorldBot.bot(greetingCounter = 0, max = 3), msg.name)
+
+          greeter ! HelloWorld.Greet(msg.name, replyTo)
+          Behaviors.same
+        }
+      }
+    //#hello-world-main-with-dispatchers
+  }
+
   //#chatroom-actor
   object ChatRoom {
     //#chatroom-protocol

akka-actor-typed/src/main/scala/akka/actor/typed/ActorSystem.scala

@@ -4,7 +4,6 @@
 
 package akka.actor.typed
 
-import scala.concurrent.ExecutionContext
 import akka.{ actor ⇒ a }
 import java.util.concurrent.{ CompletionStage, ThreadFactory }
 
@@ -16,7 +15,6 @@ import akka.actor.typed.internal.adapter.{ ActorSystemAdapter, PropsAdapter }
 import akka.util.Timeout
 import akka.annotation.DoNotInherit
 import akka.annotation.ApiMayChange
-import java.util.Optional
 
 import akka.actor.BootstrapSetup
 import akka.actor.typed.internal.adapter.GuardianActorAdapter

akka-actor-typed/src/main/scala/akka/actor/typed/Props.scala

@@ -148,19 +148,19 @@ sealed abstract class DispatcherSelector extends Props
  * on the options.
  *
  * The default configuration if none of these options are present is to run
- * the actor on the same executor as its parent.
+ * the actor on the default [[ActorSystem]] executor.
  */
 object DispatcherSelector {
 
   /**
    * Scala API:
-   * Run the actor on the same executor as its parent.
+   * Run the actor on the default [[ActorSystem]] executor.
    */
   def default(): DispatcherSelector = DispatcherDefault()
 
   /**
    * Java API:
-   * Run the actor on the same executor as its parent.
+   * Run the actor on the default [[ActorSystem]] executor.
    */
   def defaultDispatcher(): DispatcherSelector = default()
 

akka-actor-typed/src/main/scala/akka/actor/typed/javadsl/Behaviors.scala

@@ -12,7 +12,6 @@ import akka.actor.typed.internal.{ BehaviorImpl, Supervisor, TimerSchedulerImpl,
 import akka.annotation.{ ApiMayChange, DoNotInherit }
 import akka.japi.function.{ Procedure2, Function2 ⇒ JapiFunction2 }
 import akka.japi.pf.PFBuilder
-import akka.util.ConstantFun
 import scala.collection.JavaConverters._
 import scala.reflect.ClassTag
 /**
@@ -245,11 +244,11 @@ object Behaviors {
    *
    * Example:
    * {{{
-   * Behavior<String> s = immutable((ctx, msg) -> {
+   * Behavior<String> s = Behaviors.receive((ctx, msg) -> {
    *     System.out.println(msg);
-   *     return same();
+   *     return Behaviors.same();
    *   });
-   * Behavior&lt;Number> n = widened(s, pf -> pf.
+   * Behavior<Number> n = Behaviors.widened(s, pf -> pf.
    *         match(BigInteger.class, i -> "BigInteger(" + i + ")").
    *         match(BigDecimal.class, d -> "BigDecimal(" + d + ")")
    *         // drop all other kinds of Number

akka-docs/src/main/paradox/typed/actor-lifecycle.md

@@ -16,7 +16,41 @@ TODO intro
 
 ## Creating Actors
 
-TODO
+An actor can create, or _spawn_, an arbitrary number of child actors, which in turn can spawn children of their own, thus
+forming an actor hierarchy. @unidoc[akka.actor.typed.ActorSystem] hosts the hierarchy and there can be only one _root actor_,
+actor at the top of the hierarchy, per `ActorSystem`. The lifecycle of a child actor is tied to the parent -- a child
+can stop itself or be stopped at any time but it can never outlive its parent.
+
+The root actor, also called the guardian actor, is created along with the `ActorSystem`. Messages sent to the actor system are directed to the root actor.
+The root actor is defined by the behavior used to create the `ActorSystem`, named `HelloWorldMain.main` in the example below:
+
+Scala
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world }
+
+Java
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world }
+
+
+Child actors are spawned with @unidoc[akka.actor.typed.ActorContext]'s `spawn`. In the example below, when the root actor
+is started, it spawns a child actor described by the behavior `HelloWorld.greeter`. Additionally, when the root actor receives a
+`Start` message, it creates a child actor defined by the behavior `HelloWorldBot.bot`:
+
+Scala
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main }
+
+Java
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main }
+
+To specify a dispatcher when spawning an actor use @unidoc[DispatcherSelector]. If not specified, the actor will
+use the default dispatcher, see @ref:[Default dispatcher](../dispatchers.md#default-dispatcher) for details.
+
+Scala
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main-with-dispatchers }
+
+Java
+:  @@snip [IntroSpec.scala]($akka$/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main-with-dispatchers }
+
+Refer to @ref:[Actors](actors.md#introduction) for a walk-through of the above examples.
 
 ## Stopping Actors