+per #3746 Remote sharing of LevelDB for testing purposes

Further changes

- remove obsolete identity checks in Eventsourced
- fix wrong serialize-messages config in tests

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

@@ -5,6 +5,7 @@
 package docs.persistence;
 
 //#plugin-imports
+import akka.actor.UntypedActor;
 import scala.concurrent.Future;
 import akka.japi.Option;
 import akka.japi.Procedure;
@@ -12,8 +13,44 @@ import akka.persistence.*;
 import akka.persistence.journal.japi.*;
 import akka.persistence.snapshot.japi.*;
 //#plugin-imports
+import akka.actor.*;
+import akka.persistence.journal.leveldb.SharedLeveldbJournal;
+import akka.persistence.journal.leveldb.SharedLeveldbStore;
 
 public class PersistencePluginDocTest {
+
+
+    static Object o1 = new Object() {
+        final ActorSystem system = null;
+        //#shared-store-creation
+        final ActorRef store = system.actorOf(Props.create(SharedLeveldbStore.class), "store");
+        //#shared-store-creation
+
+        //#shared-store-usage
+        class SharedStorageUsage extends UntypedActor {
+            @Override
+            public void preStart() throws Exception {
+                String path = "akka.tcp://example@127.0.0.1:2552/user/store";
+                ActorSelection selection = getContext().actorSelection(path);
+                selection.tell(new Identify(1), getSelf());
+            }
+
+            @Override
+            public void onReceive(Object message) throws Exception {
+                if (message instanceof ActorIdentity) {
+                    ActorIdentity identity = (ActorIdentity) message;
+                    if (identity.correlationId().equals(1)) {
+                        ActorRef store = identity.getRef();
+                        if (store != null) {
+                            SharedLeveldbJournal.setStore(store, getContext().system());
+                        }
+                    }
+                }
+            }
+        }
+        //#shared-store-usage
+    };
+
     class MySnapshotStore extends SnapshotStore {
         @Override
         public Future<Option<SelectedSnapshot>> doLoadAsync(String processorId, SnapshotSelectionCriteria criteria) {

akka-docs/rst/java/persistence.rst

@@ -60,19 +60,6 @@ Architecture
 * *Event sourcing*. Based on the building blocks described above, Akka persistence provides abstractions for the
   development of event sourced applications (see section :ref:`event-sourcing-java`)
 
-Configuration
-=============
-
-By default, journaled messages are written to a directory named ``journal`` in the current working directory. This
-can be changed by configuration where the specified path can be relative or absolute:
-
-.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#journal-config
-
-The default storage location of :ref:`snapshots-java` is a directory named ``snapshots`` in the current working directory.
-This can be changed by configuration where the specified path can be relative or absolute:
-
-.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#snapshot-config
-
 .. _processors-java:
 
 Processors
@@ -407,10 +394,11 @@ will therefore never be done partially i.e. with only a subset of events persist
 Storage plugins
 ===============
 
-Storage backends for journals and snapshot stores are plugins in akka-persistence. The default journal plugin writes
-messages to LevelDB. The default snapshot store plugin writes snapshots as individual files to the local filesystem.
-Applications can provide their own plugins by implementing a plugin API and activate them by configuration. Plugin
-development requires the following imports:
+Storage backends for journals and snapshot stores are plugins in akka-persistence. The default journal plugin
+writes messages to LevelDB (see :ref:`local-leveldb-journal-java`). The default snapshot store plugin writes snapshots
+as individual files to the local filesystem (see :ref:`local-snapshot-store-java`). Applications can provide their own
+plugins by implementing a plugin API and activate them by configuration. Plugin development requires the following
+imports:
 
 .. includecode:: code/docs/persistence/PersistencePluginDocTest.java#plugin-imports
 
@@ -454,6 +442,67 @@ A snapshot store plugin can be activated with the following minimal configuratio
 The specified plugin ``class`` must have a no-arg constructor. The ``plugin-dispatcher`` is the dispatcher
 used for the plugin actor. If not specified, it defaults to ``akka.persistence.dispatchers.default-plugin-dispatcher``.
 
+Pre-packaged plugins
+====================
+
+.. _local-leveldb-journal-java:
+
+Local LevelDB journal
+---------------------
+
+The default journal plugin is ``akka.persistence.journal.leveldb`` which writes messages to a local LevelDB
+instance. The default location of the LevelDB files is a directory named ``journal`` in the current working
+directory. This location can be changed by configuration where the specified path can be relative or absolute:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#journal-config
+
+With this plugin, each actor system runs its own private LevelDB instance.
+
+Shared LevelDB journal
+----------------------
+
+A LevelDB instance can also be shared by multiple actor systems (on the same or on different nodes). This, for
+example, allows processors to failover to a backup node, assuming that the node, where the shared instance is
+runnning, is accessible from the backup node.
+
+.. warning::
+
+  A shared LevelDB instance is a single point of failure and should therefore only be used for testing
+  purposes.
+
+A shared LevelDB instance can be created by instantiating the ``SharedLeveldbStore`` actor.
+
+.. includecode:: code/docs/persistence/PersistencePluginDocTest.java#shared-store-creation
+
+By default, the shared instance writes journaled messages to a local directory named ``journal`` in the current
+working directory. The storage location can be changed by configuration:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#shared-store-config
+
+Actor systems that use a shared LevelDB store must activate the ``akka.persistence.journal.leveldb-shared``
+plugin.
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#shared-journal-config
+
+This plugin must be initialized by injecting the (remote) ``SharedLeveldbStore`` actor reference. Injection is
+done by calling the ``SharedLeveldbJournal.setStore`` method with the actor reference as argument.
+
+.. includecode:: code/docs/persistence/PersistencePluginDocTest.java#shared-store-usage
+
+Internal journal commands (sent by processors) are buffered until injection completes. Injection is idempotent
+i.e. only the first injection is used.
+
+.. _local-snapshot-store-java:
+
+Local snapshot store
+--------------------
+
+The default snapshot store plugin is ``akka.persistence.snapshot-store.local`` which writes snapshot files to
+the local filesystem. The default storage location is a directory named ``snapshots`` in the current working
+directory. This can be changed by configuration where the specified path can be relative or absolute:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#snapshot-config
+
 Custom serialization
 ====================