raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Reword the "Where to define messages" style docs (#27393)

Browse source
This commit is contained in:
Dale Wijnand 2019-07-24 12:26:43 +01:00 • committed by Johannes Rudolph
parent 38be540467
commit 5997f516de
1 changed files with 10 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

21
akka-docs/src/main/paradox/typed/style-guide.md
View file

@ -235,8 +235,8 @@ Java
## Where to define messages ## Where to define messages
When sending messages to another actor or receiving responses the messages should be prefixed with the name When sending or receiving actor messages they should be prefixed with the name
of the actor/behavior that defines the message to make it clear and avoid ambiguity. of the actor/behavior that defines them to avoid ambiguities.
Scala Scala
: @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #message-prefix-in-tell } : @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #message-prefix-in-tell }
@ -244,14 +244,14 @@ Scala
Java Java
: @@snip [StyleGuideDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/StyleGuideDocExamples.java) { #message-prefix-in-tell } : @@snip [StyleGuideDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/StyleGuideDocExamples.java) { #message-prefix-in-tell }
That is preferred over using @scala[importing `Down` and using `countDown ! Down`] Such a style is preferred over using @scala[importing `Down` and using `countDown ! Down`]
@java[importing `Down` and using `countDown.tell(Down.INSTANCE);`]. @java[importing `Down` and using `countDown.tell(Down.INSTANCE);`].
In the implementation of the `Behavior` that handle these messages the short names can be used. However, within the `Behavior` that handle these messages the short names can be used.
That is a reason for not defining the messages as top level classes in a package. Therefore it is not recommended to define messages as top-level classes.
An actor typically has a primary `Behavior` or it's only using one `Behavior` and then it's good to define For the majority of cases it's good style to define
the messages @scala[in the companion object]@java[as static inner classes] together with that `Behavior`. the messages @scala[in the companion object]@java[as static inner classes] together with the `Behavior`.
Scala Scala
: @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #messages } : @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #messages }
@ -259,11 +259,10 @@ Scala
Java Java
: @@snip [StyleGuideDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/StyleGuideDocExamples.java) { #messages } : @@snip [StyleGuideDocExamples.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/StyleGuideDocExamples.java) { #messages }
Sometimes several actors share the same messages, because they have a tight coupling and using message adapters If several actors share the same message protocol, it's recommended to define
would introduce to much boilerplate and duplication. If there is no "natural home" for such messages they can be those messages in a separate @scala[`object`]@java[`interface`] for that protocol.
be defined in a separate @scala[`object`]@java[`interface`] to give them a naming scope.
Example of shared message protocol: Here's an example of a shared message protocol setup:
Scala Scala
: @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #message-protocol } : @@snip [StyleGuideDocExamples.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/StyleGuideDocExamples.scala) { #message-protocol }