+per #3641 Storage plugin API

- Journal plugin API for storage backends with asynchronous client API (default impl: in-memory journal)
- Journal plugin API for storage backends with synchronous client API (default impl: LevelDB journal)
- Snapshot store plugin API (default impl: local filesystem snapshot store)

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

@@ -2,31 +2,27 @@ package docs.persistence
 
 import akka.actor.ActorSystem
 import akka.persistence._
-import akka.persistence.SaveSnapshotSucceeded
-import scala.Some
 
 trait PersistenceDocSpec {
   val system: ActorSystem
-  val config =
-    """
-      //#journal-config
-      akka.persistence.journal.leveldb.dir = "target/journal"
-      //#journal-config
-      //#snapshot-config
-      akka.persistence.snapshot-store.local.dir = "target/snapshots"
-      //#snapshot-config
-    """
 
   import system._
 
   new AnyRef {
     //#definition
-    import akka.persistence.{ Persistent, Processor }
+    import akka.persistence.{ Persistent, PersistenceFailure, Processor }
 
     class MyProcessor extends Processor {
       def receive = {
-        case Persistent(payload, sequenceNr) ⇒ // message has been written to journal
-        case other                           ⇒ // message has not been written to journal
+        case Persistent(payload, sequenceNr) ⇒ {
+          // message successfully written to journal
+        }
+        case PersistenceFailure(payload, sequenceNr, cause) ⇒ {
+          // message failed to be written to journal
+        }
+        case other ⇒ {
+          // message not written to journal
+        }
       }
     }
     //#definition
@@ -195,9 +191,9 @@ trait PersistenceDocSpec {
       var state: Any = _
 
       def receive = {
-        case "snap"                               ⇒ saveSnapshot(state)
-        case SaveSnapshotSucceeded(metadata)      ⇒ // ...
-        case SaveSnapshotFailed(metadata, reason) ⇒ // ...
+        case "snap"                                ⇒ saveSnapshot(state)
+        case SaveSnapshotSuccess(metadata)         ⇒ // ...
+        case SaveSnapshotFailure(metadata, reason) ⇒ // ...
       }
     }
     //#save-snapshot

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

@@ -0,0 +1,78 @@
+package docs.persistence
+
+//#plugin-imports
+import scala.concurrent.Future
+//#plugin-imports
+
+import com.typesafe.config._
+
+import org.scalatest.WordSpec
+
+import akka.actor.ActorSystem
+//#plugin-imports
+import akka.persistence._
+import akka.persistence.journal._
+import akka.persistence.snapshot._
+//#plugin-imports
+
+object PersistencePluginDocSpec {
+  val config =
+    """
+      //#journal-config
+      akka.persistence.journal.leveldb.dir = "target/journal"
+      //#journal-config
+      //#snapshot-config
+      akka.persistence.snapshot-store.local.dir = "target/snapshots"
+      //#snapshot-config
+    """
+}
+
+class PersistencePluginDocSpec extends WordSpec {
+  new AnyRef {
+    val providerConfig =
+      """
+        //#journal-plugin-config
+        # Path to the journal plugin to be used
+        akka.persistence.journal.plugin = "my-journal"
+
+        # My custom journal plugin
+        my-journal {
+          # Class name of the plugin.
+          class = "docs.persistence.MyJournal"
+          # Dispatcher for the plugin actor.
+          plugin-dispatcher = "akka.actor.default-dispatcher"
+        }
+        //#journal-plugin-config
+
+        //#snapshot-store-plugin-config
+        # Path to the snapshot store plugin to be used
+        akka.persistence.snapshot-store.plugin = "my-snapshot-store"
+
+        # My custom snapshot store plugin
+        my-snapshot-store {
+          # Class name of the plugin.
+          class = "docs.persistence.MySnapshotStore"
+          # Dispatcher for the plugin actor.
+          plugin-dispatcher = "akka.persistence.dispatchers.default-plugin-dispatcher"
+        }
+        //#snapshot-store-plugin-config
+      """
+
+    val system = ActorSystem("doc", ConfigFactory.parseString(providerConfig).withFallback(ConfigFactory.parseString(PersistencePluginDocSpec.config)))
+    val extension = Persistence(system)
+  }
+}
+
+class MyJournal extends AsyncWriteJournal {
+  def writeAsync(persistent: PersistentImpl): Future[Unit] = ???
+  def deleteAsync(persistent: PersistentImpl): Future[Unit] = ???
+  def confirmAsync(processorId: String, sequenceNr: Long, channelId: String): Future[Unit] = ???
+  def replayAsync(processorId: String, fromSequenceNr: Long, toSequenceNr: Long)(replayCallback: (PersistentImpl) ⇒ Unit): Future[Long] = ???
+}
+
+class MySnapshotStore extends SnapshotStore {
+  def loadAsync(processorId: String, criteria: SnapshotSelectionCriteria): Future[Option[SelectedSnapshot]] = ???
+  def saveAsync(metadata: SnapshotMetadata, snapshot: Any): Future[Unit] = ???
+  def saved(metadata: SnapshotMetadata) {}
+  def delete(metadata: SnapshotMetadata) {}
+}