Merge pull request #27272 from akka/wip-22805-helloworld-patriknw

Style: Update HelloWorld sample to OO style for Java, #22805

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

@@ -75,8 +75,8 @@ is a tool that mimics the old style of starting up actors.
 
 Child actors are spawned with @apidoc[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`:
+is started, it spawns a child actor described by the `HelloWorld` behavior. Additionally, when the root actor receives a
+`Start` message, it creates a child actor defined by the behavior `HelloWorldBot`:
 
 Scala
 :  @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main }

akka-docs/src/main/paradox/typed/actors.md

@@ -40,23 +40,27 @@ greet, it also holds an `ActorRef` that the sender of the message
 supplies so that the `HelloWorld` Actor can send back the confirmation
 message.
 
-The behavior of the Actor is defined as the `greeter` value with the help
+The behavior of the Actor is defined as the `Greeter` with the help
 of the `receive` behavior factory. Processing the next message then results
 in a new behavior that can potentially be different from this one. State is
 updated by returning a new behavior that holds the new immutable state. In this
-case we don't need to update any state, so we return `same`, which means
+case we don't need to update any state, so we return @scala[`same`]@java[`this`], which means
 the next behavior is "the same as the current one".
 
 The type of the messages handled by this behavior is declared to be of class
-`Greet`, meaning that `message` argument is
-also typed as such. This is why we can access the `whom` and `replyTo`
-members without needing to use a pattern match.
+`Greet`@java[.]@scala[, meaning that `message` argument is also typed as such.
+This is why we can access the `whom` and `replyTo` members without needing to use a pattern match.]
+Typically, an actor handles more than one specific message type and then there
+is one common @scala[`trait`]@java[`interface`] that all messages that the
+actor can handle @scala[`extends`]@java[`implements`].
 
 On the last line we see the `HelloWorld` Actor send a message to another
-Actor, which is done using the @scala[`!` operator (pronounced “bang” or “tell”).]@java[`tell` method.]
+Actor, which is done using the @scala[`!` operator (pronounced “bang” or “tell”)]@java[`tell` method].
+It is an asynchronous operation that doesn't block the caller's thread.
+
 Since the `replyTo` address is declared to be of type @scala[`ActorRef[Greeted]`]@java[`ActorRef<Greeted>`], the
 compiler will only permit us to send messages of this type, other usage will
-not be accepted.
+be a compiler error.
 
 The accepted message types of an Actor together with all reply types defines
 the protocol spoken by this Actor; in this case it is a simple request–reply
@@ -65,8 +69,8 @@ protocol is bundled together with the behavior that implements it in a nicely
 wrapped scope—the `HelloWorld` @scala[object]@java[class].
 
 As Carl Hewitt said, one Actor is no Actor—it would be quite lonely with
-nobody to talk to. We need another Actor that interacts with the `greeter`.
-Let's make a `bot` that receives the reply from the `greeter` and sends a number
+nobody to talk to. We need another Actor that interacts with the `Greeter`.
+Let's make a `HelloWorldBot` that receives the reply from the `Greeter` and sends a number
 of additional greeting messages and collect the replies until a given max number
 of messages have been reached.
 
@@ -76,12 +80,12 @@ Scala
 Java
 :  @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-bot }
 
-Note how this Actor manages the counter by changing the behavior for each `Greeted` reply
-rather than using any variables.
+@scala[Note how this Actor manages the counter by changing the behavior for each `Greeted` reply
+rather than using any variables.]@java[Note how this Actor manages the counter with an instance variable.]
+No concurrency guards such as `synchronized` or `AtomicInteger` are needed since an actor instance processes one
+message at a time.
 
-
-
-A third actor spawns the `greeter` and the `bot` and starts the interaction between those.
+A third actor spawns the `Greeter` and the `HelloWorldBot` and starts the interaction between those.
 
 Scala
 :  @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main }
@@ -97,8 +101,8 @@ Scala
 Java
 :  @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world }
 
-We start an Actor system from the defined `main` behavior and send two `Start` messages that
-will kick-off the interaction between two separate `bot` actors and the single `greeter` actor.
+We start an Actor system from the defined `HelloWorldMain` behavior and send two `Start` messages that
+will kick-off the interaction between two separate `HelloWorldBot` actors and the single `Greeter` actor.
 
 An application normally consists of a single `ActorSystem`, running many actors, per JVM.