Merge pull request #16365 from hicolour/fix-16364-doc-persistent-actor-recovery-customization-hicolour

=doc #16364 Persistent actor - clarification of the recovery cust...

akka-docs/rst/java/code/docs/persistence/PersistenceDocTest.java

@@ -71,8 +71,8 @@ public class PersistenceDocTest {
                 //#usage
                 processor = getContext().actorOf(Props.create(MyProcessor.class), "myProcessor");
 
-                processor.tell(Persistent.create("foo"), null);
-                processor.tell("bar", null);
+                processor.tell(Persistent.create("foo"), getSelf());
+                processor.tell("bar", getSelf());
                 //#usage
             }
 
@@ -82,7 +82,7 @@ public class PersistenceDocTest {
 
             private void recover() {
                 //#recover-explicit
-                processor.tell(Recover.create(), null);
+                processor.tell(Recover.create(), getSelf());
                 //#recover-explicit
             }
         }
@@ -105,7 +105,7 @@ public class PersistenceDocTest {
             //#recover-on-start-custom
             @Override
             public void preStart() {
-                getSelf().tell(Recover.create(457L), null);
+                getSelf().tell(Recover.create(457L), getSelf());
             }
             //#recover-on-start-custom
         }
@@ -166,6 +166,15 @@ public class PersistenceDocTest {
             //#recovery-completed
         }
     };
+
+    static Object fullyDisabledRecoveyExample = new Object() {
+        abstract class MyProcessor1 extends UntypedPersistentActor {
+            //#recover-fully-disabled
+            @Override
+            public void preStart() { getSelf().tell(Recover.create(0L), getSelf()); }
+            //#recover-fully-disabled
+        }
+    };
     
     static Object atLeastOnceExample = new Object() {
       //#at-least-once-example
@@ -563,7 +572,7 @@ public class PersistenceDocTest {
                 final Procedure<String> replyToSender = new Procedure<String>() {
                     @Override
                     public void apply(String event) throws Exception {
-                        sender().tell(event, self());
+                        sender().tell(event, getSelf());
                     }
                 };
 

akka-docs/rst/java/persistence.rst

@@ -148,13 +148,13 @@ Recovery
 --------
 
 By default, a persistent actor is automatically recovered on start and on restart by replaying journaled messages.
-New messages sent to a persistent actor during recovery do not interfere with replayed messages. New messages will
-only be received by a persistent actor after recovery completes.
+New messages sent to a persistent actor during recovery do not interfere with replayed messages. 
+They are cached and received by a persistent actor after recovery phase completes.
 
 Recovery customization
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Automated recovery on start can be disabled by overriding ``preStart`` with an empty implementation.
+Automated recovery on start can be disabled by overriding ``preStart`` with an empty or custom implementation.
 
 .. includecode:: code/docs/persistence/PersistenceDocTest.java#recover-on-start-disabled
 
@@ -162,6 +162,14 @@ In this case, a persistent actor must be recovered explicitly by sending it a ``
 
 .. includecode:: code/docs/persistence/PersistenceDocTest.java#recover-explicit
 
+.. warning::
+If ``preStart`` is overriden by an empty implementation, incoming commands will not be processed by the
+``PersistentActor`` until it receives a ``Recover`` and finishes recovery.
+
+In order to completely skip recovery, you can signal it with ``Recover.create(0L)``
+
+.. includecode:: code/docs/persistence/PersistenceDocTest.java#recover-fully-disabled
+
 If not overridden, ``preStart`` sends a ``Recover`` message to ``getSelf()``. Applications may also override
 ``preStart`` to define further ``Recover`` parameters such as an upper sequence number bound, for example.
 

akka-docs/rst/scala/code/docs/persistence/PersistenceDocSpec.scala

@@ -110,6 +110,14 @@ trait PersistenceDocSpec {
     }
   }
 
+  new AnyRef {
+      trait MyProcessor1 extends PersistentActor {
+        //#recover-fully-disabled
+        override def preStart() = self ! Recover(toSequenceNr = 0L)
+        //#recover-fully-disabled
+      }
+  }
+
   new AnyRef {
     trait ProcessorMethods {
       //#persistence-id

akka-docs/rst/scala/persistence.rst

@@ -139,13 +139,13 @@ Recovery
 --------
 
 By default, a persistent actor is automatically recovered on start and on restart by replaying journaled messages.
-New messages sent to a persistent actor during recovery do not interfere with replayed messages. New messages will
-only be received by a persistent actor after recovery completes.
+New messages sent to a persistent actor during recovery do not interfere with replayed messages. 
+They are cached and received by a persistent actor after recovery phase completes.
 
 Recovery customization
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Automated recovery on start can be disabled by overriding ``preStart`` with an empty implementation.
+Automated recovery on start can be disabled by overriding ``preStart`` with an empty or custom implementation.
 
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#recover-on-start-disabled
 
@@ -153,6 +153,14 @@ In this case, a persistent actor must be recovered explicitly by sending it a ``
 
 .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#recover-explicit
 
+.. warning::
+If ``preStart`` is overriden by an empty implementation, incoming commands will not be processed by the
+``PersistentActor`` until it receives a ``Recover`` and finishes recovery.
+
+In order to completely skip recovery, you can signal it with ``Recover(toSequenceNr = OL)``
+
+.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#recover-fully-disabled
+
 If not overridden, ``preStart`` sends a ``Recover()`` message to ``self``. Applications may also override
 ``preStart`` to define further ``Recover()`` parameters such as an upper sequence number bound, for example.