diff --git a/akka-docs/rst/java/persistence.rst b/akka-docs/rst/java/persistence.rst index 43f1d2603b..688211bc8d 100644 --- a/akka-docs/rst/java/persistence.rst +++ b/akka-docs/rst/java/persistence.rst @@ -240,6 +240,24 @@ request instructs a channel to send a ``Persistent`` message to a destination. ``ActorPath`` and messages are sent by the channel via that path's ``ActorSelection``. Sender references are preserved by a channel, therefore, a destination can reply to the sender of a ``Deliver`` request. +.. note:: + + Sending via a channel has at-least-once delivery semantics—by virtue of either + the sending actor or the channel being persistent—which means that the + semantics do not match those of a normal :class:`ActorRef` send operation: + + * it is not at-most-once delivery + + * message order for the same sender–receiver pair is not retained due to + possible resends + + * after a crash and restart of the destination messages are still + delivered—to the new actor incarnation + + These semantics match precisely what an :class:`ActorPath` represents (see + :ref:`actor-lifecycle-java`), therefore you need to supply a path and not a + reference when constructing :class:`Deliver` messages. + If a processor wants to reply to a ``Persistent`` message sender it should use the ``getSender()`` path as channel destination. diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst index 3fa1b8754b..2e59a023e6 100644 --- a/akka-docs/rst/java/untyped-actors.rst +++ b/akka-docs/rst/java/untyped-actors.rst @@ -217,6 +217,8 @@ described in the following: The implementations shown above are the defaults provided by the :class:`UntypedActor` class. +.. _actor-lifecycle-java: + Actor Lifecycle --------------- diff --git a/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst b/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst index ee159b9bdb..a5e5cf02e0 100644 --- a/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst +++ b/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst @@ -27,7 +27,7 @@ Eventsourced and Akka Persistence are both :ref:`extending-akka-scala`. **Eventsourced:** ``EventsourcingExtension`` - Must be explicitly created with an actor system and an application-defined journal actor as arguments. - (see `usage example `_). + (see `example usage `_). - `Processors `_ and `Channels `_ must be created with the factory methods ``processorOf`` and ``channelOf`` defined on ``EventsourcingExtension``. diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst index 4e7be27c2f..d885a64917 100644 --- a/akka-docs/rst/scala/actors.rst +++ b/akka-docs/rst/scala/actors.rst @@ -255,6 +255,8 @@ described in the following: The implementations shown above are the defaults provided by the :class:`Actor` trait. +.. _actor-lifecycle-scala: + Actor Lifecycle --------------- diff --git a/akka-docs/rst/scala/persistence.rst b/akka-docs/rst/scala/persistence.rst index eaf68d4dca..1db8d8607e 100644 --- a/akka-docs/rst/scala/persistence.rst +++ b/akka-docs/rst/scala/persistence.rst @@ -237,6 +237,24 @@ request instructs a channel to send a ``Persistent`` message to a destination. ``ActorPath`` and messages are sent by the channel via that path's ``ActorSelection``. Sender references are preserved by a channel, therefore, a destination can reply to the sender of a ``Deliver`` request. +.. note:: + + Sending via a channel has at-least-once delivery semantics—by virtue of either + the sending actor or the channel being persistent—which means that the + semantics do not match those of a normal :class:`ActorRef` send operation: + + * it is not at-most-once delivery + + * message order for the same sender–receiver pair is not retained due to + possible resends + + * after a crash and restart of the destination messages are still + delivered—to the new actor incarnation + + These semantics match precisely what an :class:`ActorPath` represents (see + :ref:`actor-lifecycle-scala`), therefore you need to supply a path and not a + reference when constructing :class:`Deliver` messages. + If a processor wants to reply to a ``Persistent`` message sender it should use the ``sender`` path as channel destination.