Merge pull request #16877 from pawelkaczor/master

=doc #16874 clean up `Relationship between deliver and confirmDelivery` section

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

@@ -422,22 +422,21 @@ this will send the message to the destination actor. When recovering, messages w
 Once recovery has completed, if there are outstanding messages that have not been confirmed (during the message replay), 
 the persistent actor will resend these before sending any other messages.
 
-Deliver also requires a function to pass the ``deliveryId`` into the message. A ``deliveryId`` is required to acknowledge 
+Deliver requires a ``deliveryIdToMessage`` function to pass the provided ``deliveryId`` into the message so that correlation 
-receipt of a message, and is also used in playback, when the actor is recovering so that messages received can be correctly acknowledged. 
+between ``deliver`` and ``confirmDelivery`` is possible. The ``deliveryId`` must do the round trip. Upon receipt 
-A function can be created to map your own ``messageId`` to ``deliveryId``, which may come from your own domain model. 
+of the message, destination actor will send the same``deliveryId`` wrapped in a confirmation message back to the sender. 
-This function must keep track of which ``messageId`` have been acknowledged.
+The sender will then use it to call ``confirmDelivery`` method to complete delivery routine.
-Alternatively, the Persistence module provides a default sequence number implementation which can also be used as the ``deliveryId`` 
-for messages. The default sequence increases monotonically, without gaps.
 
 .. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#at-least-once-example
 
-Correlation between ``deliver`` and ``confirmDelivery`` is performed with the ``deliveryId`` that is provided
+The ``deliveryId`` generated by the persistence module is a strictly monotonically increasing sequence number 
-as parameter to the ``deliveryIdToMessage`` function. The ``deliveryId`` is typically passed in the message to the
+without gaps. The same sequence is used for all destinations of the actor, i.e. when sending to multiple 
-destination, which replies with a message containing the same ``deliveryId``.
+destinations the destinations will see gaps in the sequence. It is not possible to use custom ``deliveryId``. 
-
+However, you can send a custom correlation identifier in the message to the destination. You must then retain 
-The ``deliveryId`` is a strictly monotonically increasing sequence number without gaps. The same sequence is
+a mapping between the internal ``deliveryId`` (passed into the ``deliveryIdToMessage`` function) and your custom 
-used for all destinations of the actor, i.e. when sending to multiple destinations the destinations will see
+correlation id (passed into the message). You can do this by storing such mapping in a ``Map(correlationId -> deliveryId)`` 
-gaps in the sequence if no translation is performed.
+from which you can retrive the ``deliveryId`` to be passed into the ``confirmDelivery`` method once the receiver 
+of your message has replied with your custom correlation id.
 
 The ``AbstractPersistentActorWithAtLeastOnceDelivery`` class has a state consisting of unconfirmed messages and a
 sequence number. It does not store this state itself. You must persist events corresponding to the

akka-docs/rst/java/persistence.rst

@@ -427,22 +427,21 @@ this will send the message to the destination actor. When recovering, messages w
 Once recovery has completed, if there are outstanding messages that have not been confirmed (during the message replay), 
 the persistent actor will resend these before sending any other messages.
 
-Deliver also requires a function to pass the ``deliveryId`` into the message. A ``deliveryId`` is required to acknowledge 
+Deliver requires a ``deliveryIdToMessage`` function to pass the provided ``deliveryId`` into the message so that correlation 
-receipt of a message, and is also used in playback, when the actor is recovering so that messages received can be correctly acknowledged. 
+between ``deliver`` and ``confirmDelivery`` is possible. The ``deliveryId`` must do the round trip. Upon receipt 
-A function can be created to map your own ``messageId`` to ``deliveryId``, which may come from your own domain model. 
+of the message, destination actor will send the same``deliveryId`` wrapped in a confirmation message back to the sender. 
-This function must keep track of which ``messageId`` have been acknowledged.
+The sender will then use it to call ``confirmDelivery`` method to complete delivery routine.
-Alternatively, the Persistence module provides a default sequence number implementation which can also be used as the ``deliveryId`` 
-for messages. The default sequence increases monotonically, without gaps.
 
 .. includecode:: code/docs/persistence/PersistenceDocTest.java#at-least-once-example
 
-Correlation between ``deliver`` and ``confirmDelivery`` is performed with the ``deliveryId`` that is provided
+The ``deliveryId`` generated by the persistence module is a strictly monotonically increasing sequence number 
-as parameter to the ``deliveryIdToMessage`` function. The ``deliveryId`` is typically passed in the message to the
+without gaps. The same sequence is used for all destinations of the actor, i.e. when sending to multiple 
-destination, which replies with a message containing the same ``deliveryId``.
+destinations the destinations will see gaps in the sequence. It is not possible to use custom ``deliveryId``. 
-
+However, you can send a custom correlation identifier in the message to the destination. You must then retain 
-The ``deliveryId`` is a strictly monotonically increasing sequence number without gaps. The same sequence is
+a mapping between the internal ``deliveryId`` (passed into the ``deliveryIdToMessage`` function) and your custom 
-used for all destinations of the actor, i.e. when sending to multiple destinations the destinations will see
+correlation id (passed into the message). You can do this by storing such mapping in a ``Map(correlationId -> deliveryId)`` 
-gaps in the sequence if no translation is performed.
+from which you can retrive the ``deliveryId`` to be passed into the ``confirmDelivery`` method once the receiver 
+of your message has replied with your custom correlation id.
 
 The ``UntypedPersistentActorWithAtLeastOnceDelivery`` class has a state consisting of unconfirmed messages and a
 sequence number. It does not store this state itself. You must persist events corresponding to the

akka-docs/rst/scala/persistence.rst

@@ -425,22 +425,21 @@ this will send the message to the destination actor. When recovering, messages w
 Once recovery has completed, if there are outstanding messages that have not been confirmed (during the message replay), 
 the persistent actor will resend these before sending any other messages.
 
-Deliver also requires a function to pass the ``deliveryId`` into the message. A ``deliveryId`` is required to acknowledge 
+Deliver requires a ``deliveryIdToMessage`` function to pass the provided ``deliveryId`` into the message so that correlation 
-receipt of a message, and is also used in playback, when the actor is recovering so that messages received can be correctly acknowledged. 
+between ``deliver`` and ``confirmDelivery`` is possible. The ``deliveryId`` must do the round trip. Upon receipt 
-A function can be created to map your own ``messageId`` to ``deliveryId``, which may come from your own domain model. 
+of the message, destination actor will send the same``deliveryId`` wrapped in a confirmation message back to the sender. 
-This function must keep track of which ``messageId`` have been acknowledged.
+The sender will then use it to call ``confirmDelivery`` method to complete delivery routine.
-Alternatively, the Persistence module provides a default sequence number implementation which can also be used as the ``deliveryId`` 
-for messages. The default sequence increases monotonically, without gaps.
 
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#at-least-once-example
 
-Correlation between ``deliver`` and ``confirmDelivery`` is performed with the ``deliveryId`` that is provided
+The ``deliveryId`` generated by the persistence module is a strictly monotonically increasing sequence number 
-as parameter to the ``deliveryIdToMessage`` function. The ``deliveryId`` is typically passed in the message to the
+without gaps. The same sequence is used for all destinations of the actor, i.e. when sending to multiple 
-destination, which replies with a message containing the same ``deliveryId``.
+destinations the destinations will see gaps in the sequence. It is not possible to use custom ``deliveryId``. 
-
+However, you can send a custom correlation identifier in the message to the destination. You must then retain 
-The ``deliveryId`` is a strictly monotonically increasing sequence number without gaps. The same sequence is
+a mapping between the internal ``deliveryId`` (passed into the ``deliveryIdToMessage`` function) and your custom 
-used for all destinations of the actor, i.e. when sending to multiple destinations the destinations will see
+correlation id (passed into the message). You can do this by storing such mapping in a ``Map(correlationId -> deliveryId)`` 
-gaps in the sequence if no translation is performed.
+from which you can retrive the ``deliveryId`` to be passed into the ``confirmDelivery`` method once the receiver 
+of your message has replied with your custom correlation id.
 
 The ``AtLeastOnceDelivery`` trait has a state consisting of unconfirmed messages and a
 sequence number. It does not store this state itself. You must persist events corresponding to the