Merge pull request #1808 from krasserm/wip-3681-performance-improvements-krasserm

!per #3681 Performance and consistency improvements

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

@@ -9,6 +9,8 @@ import scala.Option;
 import akka.actor.*;
 import akka.persistence.*;
 
+import static java.util.Arrays.asList;
+
 public class PersistenceDocTest {
 
     public interface ProcessorMethods {
@@ -237,4 +239,31 @@ public class PersistenceDocTest {
             }
         }
     };
+
+    static Object o6 = new Object() {
+        //#batch-write
+        class MyProcessor extends UntypedProcessor {
+            public void onReceive(Object message) throws Exception {
+                if (message instanceof Persistent) {
+                    Persistent p = (Persistent)message;
+                    if (p.payload().equals("a")) { /* ... */ }
+                    if (p.payload().equals("b")) { /* ... */ }
+                }
+            }
+        }
+
+        class Example {
+            final ActorSystem system = ActorSystem.create("example");
+            final ActorRef processor = system.actorOf(Props.create(MyProcessor.class));
+
+            public void batchWrite() {
+                processor.tell(PersistentBatch.create(asList(
+                        Persistent.create("a"),
+                        Persistent.create("b"))), null);
+            }
+
+            // ...
+        }
+        //#batch-write
+    };
 }

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

@@ -45,6 +45,11 @@ public class PersistencePluginDocTest {
             return null;
         }
 
+        @Override
+        public Future<Void> doWriteBatchAsync(Iterable<PersistentImpl> persistentBatch) {
+            return null;
+        }
+
         @Override
         public Future<Void> doDeleteAsync(PersistentImpl persistent) {
             return null;

akka-docs/rst/java/persistence.rst

@@ -265,6 +265,8 @@ If not specified, they default to ``SnapshotSelectionCriteria.latest()`` which s
 To disable snapshot-based recovery, applications should use ``SnapshotSelectionCriteria.none()``. A recovery where no
 saved snapshot matches the specified ``SnapshotSelectionCriteria`` will replay all journaled messages.
 
+.. _event-sourcing-java:
+
 Event sourcing
 ==============
 
@@ -318,6 +320,20 @@ The example also demonstrates how to change the processor's default behavior, de
 another behavior, defined by ``otherCommandHandler``, and back using ``getContext().become()`` and
 ``getContext().unbecome()``. See also the API docs of ``persist`` for further details.
 
+Batch writes
+============
+
+Applications may also send a batch of ``Persistent`` messages to a processor via a ``PersistentBatch`` message.
+
+.. includecode:: code/docs/persistence/PersistenceDocTest.java#batch-write
+
+``Persistent`` messages contained in a ``PersistentBatch`` message are written to the journal atomically but are
+received  by the processor separately (as ``Persistent`` messages). They are also replayed separately. Batch writes
+can not only increase the throughput of a processor but may also be necessary for consistency reasons. For example,
+in :ref:`event-sourcing-java`, all events that are generated and persisted by a single command are batch-written to
+the journal. The recovery of an ``UntypedEventsourcedProcessor`` will therefore never be done partially i.e. with
+only a subset of events persisted by a single command.
+
 Storage plugins
 ===============