Merge pull request #17742 from akka/wip-15644-persist-seq-patriknw

!per #15644 Rename persist(seq) to persistAll

akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst

@@ -163,7 +163,7 @@ longer interval.
 Akka Persistence
 ================
 
-Mendatory persistenceId
+Mandatory persistenceId
 -----------------------
 
 It is now mandatory to define the ``persistenceId`` in subclasses of ``PersistentActor``, ``UntypedPersistentActor``
@@ -176,6 +176,13 @@ In case you want to preserve the old behavior of providing the actor's path as t
 implement it yourself either as a helper trait or simply by overriding ``persistenceId`` as follows::
 
     override def persistenceId = self.path.toStringWithoutAddress
+    
+Persist sequence of events
+--------------------------
+
+The ``persist`` method that takes a ``Seq`` (Scala) or ``Iterable`` (Java) of events parameter was deprecated and
+renamed to ``persistAll`` to avoid mistakes of persisting other collection types as one single event by calling
+the overloaded ``persist(event)`` method.  
 
 Secure Cookies
 ==============

akka-persistence/src/main/scala/akka/persistence/Eventsourced.scala

@@ -275,8 +275,12 @@ private[persistence] trait Eventsourced extends Snapshotter with Stash with Stas
    * @param events events to be persisted
    * @param handler handler for each persisted `events`
    */
+  final def persistAll[A](events: immutable.Seq[A])(handler: A ⇒ Unit): Unit =
+    events.foreach(persist(_)(handler)) // TODO the atomic part should be handled by issue #15377
+
+  @deprecated("use persistAll instead", "2.4")
   final def persist[A](events: immutable.Seq[A])(handler: A ⇒ Unit): Unit =
-    events.foreach(persist(_)(handler))
+    persistAll(events)(handler)
 
   /**
    * Asynchronously persists `event`. On successful persistence, `handler` is called with the
@@ -314,9 +318,13 @@ private[persistence] trait Eventsourced extends Snapshotter with Stash with Stas
    * @param events events to be persisted
    * @param handler handler for each persisted `events`
    */
-  final def persistAsync[A](events: immutable.Seq[A])(handler: A ⇒ Unit): Unit =
+  final def persistAllAsync[A](events: immutable.Seq[A])(handler: A ⇒ Unit): Unit =
     events.foreach(persistAsync(_)(handler))
 
+  @deprecated("use persistAllAsync instead", "2.4")
+  final def persistAsync[A](events: immutable.Seq[A])(handler: A ⇒ Unit): Unit =
+    persistAllAsync(events)(handler)
+
   /**
    * Defer the handler execution until all pending handlers have been executed.
    * Allows to define logic within the actor, which will respect the invocation-order-guarantee

akka-persistence/src/main/scala/akka/persistence/PersistentActor.scala

@@ -138,8 +138,12 @@ abstract class UntypedPersistentActor extends UntypedActor with Eventsourced wit
    * @param events events to be persisted.
    * @param handler handler for each persisted `events`
    */
+  final def persistAll[A](events: JIterable[A], handler: Procedure[A]): Unit =
+    persistAll(Util.immutableSeq(events))(event ⇒ handler(event))
+
+  @deprecated("use persistAll instead", "2.4")
   final def persist[A](events: JIterable[A], handler: Procedure[A]): Unit =
-    persist(Util.immutableSeq(events))(event ⇒ handler(event))
+    persistAll(events, handler)
 
   /**
    * JAVA API: asynchronously persists `event`. On successful persistence, `handler` is called with the
@@ -175,8 +179,8 @@ abstract class UntypedPersistentActor extends UntypedActor with Eventsourced wit
    * @param events events to be persisted
    * @param handler handler for each persisted `events`
    */
-  final def persistAsync[A](events: JIterable[A])(handler: A ⇒ Unit): Unit =
+  final def persistAllAsync[A](events: JIterable[A], handler: Procedure[A]): Unit =
-    super[Eventsourced].persistAsync(Util.immutableSeq(events))(event ⇒ handler(event))
+    super[Eventsourced].persistAllAsync(Util.immutableSeq(events))(event ⇒ handler(event))
 
   /**
    * Defer the handler execution until all pending handlers have been executed.
@@ -265,8 +269,12 @@ abstract class AbstractPersistentActor extends AbstractActor with PersistentActo
    * @param events events to be persisted.
    * @param handler handler for each persisted `events`
    */
+  final def persistAll[A](events: JIterable[A], handler: Procedure[A]): Unit =
+    persistAll(Util.immutableSeq(events))(event ⇒ handler(event))
+
+  @deprecated("use persistAll instead", "2.4")
   final def persist[A](events: JIterable[A], handler: Procedure[A]): Unit =
-    persist(Util.immutableSeq(events))(event ⇒ handler(event))
+    persistAll(events, handler)
 
   /**
    * Java API: asynchronously persists `event`. On successful persistence, `handler` is called with the
@@ -297,8 +305,12 @@ abstract class AbstractPersistentActor extends AbstractActor with PersistentActo
    * @param events events to be persisted
    * @param handler handler for each persisted `events`
    */
+  final def persistAllAsync[A](events: JIterable[A], handler: Procedure[A]): Unit =
+    persistAllAsync(Util.immutableSeq(events))(event ⇒ handler(event))
+
+  @deprecated("use persistAllAsync instead", "2.4")
   final def persistAsync[A](events: JIterable[A], handler: Procedure[A]): Unit =
-    persistAsync(Util.immutableSeq(events))(event ⇒ handler(event))
+    persistAllAsync(events, handler)
 
   /**
    * Defer the handler execution until all pending handlers have been executed.

akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSMActor.scala

@@ -80,7 +80,7 @@ trait PersistentFsmActor[S <: FSMState, D, E] extends PersistentActor with FSM[S
   override private[akka] def applyState(nextState: State): Unit = {
     val eventsToPersist: immutable.Seq[Any] = nextState.domainEvents.toList :+ StateChangeEvent(nextState.stateName.identifier, nextState.timeout)
     var nextData: D = stateData
-    persist[Any](eventsToPersist) {
+    persistAll[Any](eventsToPersist) {
       case domainEventTag(event) ⇒
         nextData = applyEvent(event, nextData)
       case StateChangeEvent(stateIdentifier, timeout) ⇒

akka-persistence/src/test/scala/akka/persistence/PersistentActorSpec.scala

@@ -39,22 +39,22 @@ object PersistentActorSpec {
   class Behavior1PersistentActor(name: String) extends ExamplePersistentActor(name) {
     val receiveCommand: Receive = commonBehavior orElse {
       case Cmd(data) ⇒
-        persist(Seq(Evt(s"${data}-1"), Evt(s"${data}-2")))(updateState)
+        persistAll(Seq(Evt(s"${data}-1"), Evt(s"${data}-2")))(updateState)
     }
   }
 
   class Behavior2PersistentActor(name: String) extends ExamplePersistentActor(name) {
     val receiveCommand: Receive = commonBehavior orElse {
       case Cmd(data) ⇒
-        persist(Seq(Evt(s"${data}-1"), Evt(s"${data}-2")))(updateState)
+        persistAll(Seq(Evt(s"${data}-1"), Evt(s"${data}-2")))(updateState)
-        persist(Seq(Evt(s"${data}-3"), Evt(s"${data}-4")))(updateState)
+        persistAll(Seq(Evt(s"${data}-3"), Evt(s"${data}-4")))(updateState)
     }
   }
 
   class Behavior3PersistentActor(name: String) extends ExamplePersistentActor(name) {
     val receiveCommand: Receive = commonBehavior orElse {
       case Cmd(data) ⇒
-        persist(Seq(Evt(s"${data}-11"), Evt(s"${data}-12")))(updateState)
+        persistAll(Seq(Evt(s"${data}-11"), Evt(s"${data}-12")))(updateState)
         updateState(Evt(s"${data}-10"))
     }
   }
@@ -101,7 +101,7 @@ object PersistentActorSpec {
     val newBehavior: Receive = {
       case Cmd(data) ⇒
         context.unbecome()
-        persist(Seq(Evt(s"${data}-31"), Evt(s"${data}-32")))(updateState)
+        persistAll(Seq(Evt(s"${data}-31"), Evt(s"${data}-32")))(updateState)
         updateState(Evt(s"${data}-30"))
     }
 
@@ -115,7 +115,7 @@ object PersistentActorSpec {
   class ChangeBehaviorInCommandHandlerLastPersistentActor(name: String) extends ExamplePersistentActor(name) {
     val newBehavior: Receive = {
       case Cmd(data) ⇒
-        persist(Seq(Evt(s"${data}-31"), Evt(s"${data}-32")))(updateState)
+        persistAll(Seq(Evt(s"${data}-31"), Evt(s"${data}-32")))(updateState)
         updateState(Evt(s"${data}-30"))
         context.unbecome()
     }
@@ -135,7 +135,7 @@ object PersistentActorSpec {
     }
 
     private def handleCmd(cmd: Cmd): Unit = {
-      persist(Seq(Evt(s"${cmd.data}-41"), Evt(s"${cmd.data}-42")))(updateState)
+      persistAll(Seq(Evt(s"${cmd.data}-41"), Evt(s"${cmd.data}-42")))(updateState)
     }
 
     def receiveCommand: Receive = commonBehavior orElse {

akka-samples/akka-sample-persistence-java-lambda/src/main/java/sample/persistence/PersistentActorExample.java

@@ -101,7 +101,7 @@ class ExamplePersistentActor extends AbstractPersistentActor {
                 final String data = c.getData();
                 final Evt evt1 = new Evt(data + "-" + getNumEvents());
                 final Evt evt2 = new Evt(data + "-" + (getNumEvents() + 1));
-                persist(asList(evt1, evt2), (Evt evt) -> {
+                persistAll(asList(evt1, evt2), (Evt evt) -> {
                     state.update(evt);
                     if (evt.equals(evt2)) {
                         context().system().eventStream().publish(evt);

akka-samples/akka-sample-persistence-java/src/main/java/sample/persistence/PersistentActorExample.java

@@ -95,7 +95,7 @@ class ExamplePersistentActor extends UntypedPersistentActor {
             final String data = ((Cmd)msg).getData();
             final Evt evt1 = new Evt(data + "-" + getNumEvents());
             final Evt evt2 = new Evt(data + "-" + (getNumEvents() + 1));
-            persist(asList(evt1, evt2), new Procedure<Evt>() {
+            persistAll(asList(evt1, evt2), new Procedure<Evt>() {
                 public void apply(Evt evt) throws Exception {
                     state.update(evt);
                     if (evt.equals(evt2)) {