=per #18342 Improve docs for leveldb plugin config

* clarify how to enable the plugin
* added empty class property in fallback config in reference
  to have a proper place to document that and throw a more
  specific exception if it is not defined
* also some formatting of reference.conf

akka-docs/rst/java/lambda-persistence.rst

@@ -522,6 +522,8 @@ saved snapshot matches the specified ``SnapshotSelectionCriteria`` will replay a
   Since it is acceptable for some applications to not use any snapshotting, it is legal to not configure a snapshot store,
   however Akka will log a warning message when this situation is detected and then continue to operate until
   an actor tries to store a snapshot, at which point the the operation will fail (by replying with an ``SaveSnapshotFailure`` for example).
+  
+  Note that :ref:`cluster_sharding_java` is using snapshots, so if you use Cluster Sharding you need to define a snapshot store plugin.
 
 Snapshot deletion
 -----------------
@@ -826,7 +828,24 @@ Local LevelDB journal
 ---------------------
 
 LevelDB journal plugin config entry is ``akka.persistence.journal.leveldb`` and it writes messages to a local LevelDB
-instance. The default location of the LevelDB files is a directory named ``journal`` in the current working
+instance. Enable this plugin by defining config property:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-plugin-config
+
+LevelDB based plugins will also require the following additional dependency declaration:: 
+
+  <dependency>
+    <groupId>org.iq80.leveldb</groupId>
+    <artifactId>leveldb</artifactId>
+    <version>0.7</version>
+  </dependency>
+  <dependency>
+    <groupId>org.fusesource.leveldbjni</groupId>
+    <artifactId>leveldbjni-all</artifactId>
+    <version>1.8</version>
+  </dependency>
+  
+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
@@ -875,11 +894,18 @@ Local snapshot store
 --------------------
 
 Local snapshot store plugin config entry is ``akka.persistence.snapshot-store.local`` and it writes snapshot files to
-the local filesystem. The default storage location is a directory named ``snapshots`` in the current working
+the local filesystem. Enable this plugin by defining config property:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-snapshot-plugin-config 
+
+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
 
+Note that it is not mandatory to specify a snapshot store plugin. If you don't use snapshots
+you don't have to configure it.
+
 Custom serialization
 ====================
 

akka-docs/rst/java/persistence.rst

@@ -525,6 +525,8 @@ saved snapshot matches the specified ``SnapshotSelectionCriteria`` will replay a
   Since it is acceptable for some applications to not use any snapshotting, it is legal to not configure a snapshot store,
   however Akka will log a warning message when this situation is detected and then continue to operate until
   an actor tries to store a snapshot, at which point the the operation will fail (by replying with an ``SaveSnapshotFailure`` for example).
+  
+  Note that :ref:`cluster_sharding_java` is using snapshots, so if you use Cluster Sharding you need to define a snapshot store plugin.
 
 Snapshot deletion
 -----------------
@@ -810,7 +812,24 @@ Local LevelDB journal
 ---------------------
 
 LevelDB journal plugin config entry is ``akka.persistence.journal.leveldb`` and it writes messages to a local LevelDB
-instance. The default location of the LevelDB files is a directory named ``journal`` in the current working
+instance. Enable this plugin by defining config property:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-plugin-config
+
+LevelDB based plugins will also require the following additional dependency declaration:: 
+
+  <dependency>
+    <groupId>org.iq80.leveldb</groupId>
+    <artifactId>leveldb</artifactId>
+    <version>0.7</version>
+  </dependency>
+  <dependency>
+    <groupId>org.fusesource.leveldbjni</groupId>
+    <artifactId>leveldbjni-all</artifactId>
+    <version>1.8</version>
+  </dependency>
+
+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
@@ -859,11 +878,18 @@ Local snapshot store
 --------------------
 
 Local snapshot store plugin config entry is ``akka.persistence.snapshot-store.local`` and it writes snapshot files to
-the local filesystem. The default storage location is a directory named ``snapshots`` in the current working
+the local filesystem. Enable this plugin by defining config property:
+
+.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-snapshot-plugin-config 
+
+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
 
+Note that it is not mandatory to specify a snapshot store plugin. If you don't use snapshots
+you don't have to configure it.
+
 Custom serialization
 ====================
 

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

@@ -26,8 +26,18 @@ import akka.persistence.snapshot._
 object PersistencePluginDocSpec {
   val config =
     """
+      //#leveldb-plugin-config
+      # Path to the journal plugin to be used
+      akka.persistence.journal.plugin = "akka.persistence.journal.leveldb"
+      //#leveldb-plugin-config
+
+      //#leveldb-snapshot-plugin-config
+      # Path to the snapshot store plugin to be used
+      akka.persistence.snapshot-store.plugin = "akka.persistence.snapshot-store.local"
+      //#leveldb-snapshot-plugin-config
+
       //#max-message-batch-size
-      akka.persistence.journal.max-message-batch-size = 200
+      akka.persistence.journal.leveldb.max-message-batch-size = 200
       //#max-message-batch-size
       //#journal-config
       akka.persistence.journal.leveldb.dir = "target/journal"

akka-docs/rst/scala/persistence.rst

@@ -516,6 +516,8 @@ saved snapshot matches the specified ``SnapshotSelectionCriteria`` will replay a
   Since it is acceptable for some applications to not use any snapshotting, it is legal to not configure a snapshot store,
   however Akka will log a warning message when this situation is detected and then continue to operate until
   an actor tries to store a snapshot, at which point the the operation will fail (by replying with an ``SaveSnapshotFailure`` for example).
+  
+  Note that :ref:`cluster_sharding_scala` is using snapshots, so if you use Cluster Sharding you need to define a snapshot store plugin.
 
 Snapshot deletion
 -----------------
@@ -866,7 +868,16 @@ Local LevelDB journal
 ---------------------
 
 LevelDB journal plugin config entry is ``akka.persistence.journal.leveldb`` and it writes messages to a local LevelDB
-instance. The default location of the LevelDB files is a directory named ``journal`` in the current working
+instance. Enable this plugin by defining config property:
+
+.. includecode:: code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-plugin-config
+
+LevelDB based plugins will also require the following additional dependency declaration::
+
+  "org.iq80.leveldb"            % "leveldb"          % "0.7"
+  "org.fusesource.leveldbjni"   % "leveldbjni-all"   % "1.8"
+
+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:: code/docs/persistence/PersistencePluginDocSpec.scala#journal-config
@@ -916,11 +927,18 @@ Local snapshot store
 --------------------
 
 Local snapshot store plugin config entry is ``akka.persistence.snapshot-store.local`` and it writes snapshot files to
-the local filesystem. The default storage location is a directory named ``snapshots`` in the current working
+the local filesystem. Enable this plugin by defining config property:
+
+.. includecode:: code/docs/persistence/PersistencePluginDocSpec.scala#leveldb-snapshot-plugin-config 
+
+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:: code/docs/persistence/PersistencePluginDocSpec.scala#snapshot-config
 
+Note that it is not mandatory to specify a snapshot store plugin. If you don't use snapshots
+you don't have to configure it.
+
 .. _custom-serialization:
 
 Custom serialization

akka-persistence/src/main/resources/reference.conf

@@ -5,32 +5,31 @@
 # This is the reference config file that contains all the default settings.
 # Make your edits in your application.conf in order to override these settings.
 
-# Note that both journal and snapshot store plugin configuration entries require few fields:
+# Directory of persistence journal and snapshot store plugins is available at the 
-# `class` : Fully qualified class name providing journal-plugin-api or snapshot-store-plugin-api implementation,
+# Akka Community Projects page http://akka.io/community/
-#           The class must have a constructor without parameters or constructor with 
-#           one `com.typesafe.config.Config` parameter.
-# `plugin-dispatcher` : Absolute configuration path to the akka dispatcher configuration entry. This string field is optional.  
-
-# Note that journal and snapshot store plugins included with the extension are suitable for testing purposes only.
-# You should change extension defaults or override `journalPluginId` and `snapshotPluginId` in the persistent actor or view.
-# Directory of persistence journal and snapshot store plugins is available at the Akka Community Projects page 
-# http://akka.io/community/
 
 # Default persistence extension settings.
 akka.persistence {
-    # Default journal settings.
     journal {
-        # Absolute path to the journal plugin configuration entry used by persistent actor or view by default.
+        # Absolute path to the journal plugin configuration entry used by 
-        # Persistent actor or view can override `journalPluginId` method in order to rely on a different journal plugin.
+        # persistent actor or view by default.
+        # Persistent actor or view can override `journalPluginId` method 
+        # in order to rely on a different journal plugin.
         plugin = ""
     }
-    # Default snapshot store settings.
     snapshot-store {
-        # Absolute path to the snapshot plugin configuration entry used by persistent actor or view by default.
+        # Absolute path to the snapshot plugin configuration entry used by
-        # Persistent actor or view can override `snapshotPluginId` method in order to rely on a different snapshot plugin.
+        # persistent actor or view by default.
+        # Persistent actor or view can override `snapshotPluginId` method
+        # in order to rely on a different snapshot plugin.
+        # It is not mandatory to specify a snapshot store plugin.
+        # If you don't use snapshots you don't have to configure it.
+        # Note that Cluster Sharding is using snapshots, so if you
+        # use Cluster Sharding you need to define a snapshot store plugin. 
         plugin = ""
     }
-    # used as default-snapshot store if no plugin configured (see `akka.persistence.snapshot-store`)
+    # used as default-snapshot store if no plugin configured 
+    # (see `akka.persistence.snapshot-store`)
     no-snapshot-store {
       class = "akka.persistence.snapshot.NoSnapshotStore"
     }
@@ -40,23 +39,28 @@ akka.persistence {
         auto-update = on
         # Interval between incremental updates.
         auto-update-interval = 5s
-        # Maximum number of messages to replay per incremental view update. Set to -1 for no upper limit.
+        # Maximum number of messages to replay per incremental view update. 
+        # Set to -1 for no upper limit.
         auto-update-replay-max = -1
     }
     # Default reliable delivery settings.
     at-least-once-delivery {
         # Interval between re-delivery attempts.
         redeliver-interval = 5s
-        # Maximum number of unconfirmed messages that will be sent in one re-delivery burst.
+        # Maximum number of unconfirmed messages that will be sent in one 
+        # re-delivery burst.
         redelivery-burst-limit = 10000
-        # After this number of delivery attempts a `ReliableRedelivery.UnconfirmedWarning`, message will be sent to the actor.
+        # After this number of delivery attempts a 
+        # `ReliableRedelivery.UnconfirmedWarning`, message will be sent to the actor.
         warn-after-number-of-unconfirmed-attempts = 5
-        # Maximum number of unconfirmed messages that an actor with AtLeastOnceDelivery is allowed to hold in memory.
+        # Maximum number of unconfirmed messages that an actor with 
+        # AtLeastOnceDelivery is allowed to hold in memory.
         max-unconfirmed-messages = 100000
     }
     # Default persistent extension thread pools.
     dispatchers {
-        # Dispatcher used by every plugin which does not declare explicit `plugin-dispatcher` field.
+        # Dispatcher used by every plugin which does not declare explicit
+        # `plugin-dispatcher` field.
         default-plugin-dispatcher {
             type = PinnedDispatcher
             executor = "thread-pool-executor"
@@ -84,6 +88,12 @@ akka.persistence {
     # Fallback settings for journal plugin configurations.
     # These settings are used if they are not defined in plugin config section.
     journal-plugin-fallback {
+    
+      # Fully qualified class name providing journal plugin api implementation.
+      # It is mandatory to specify this property.
+      # The class must have a constructor without parameters or constructor with
+      # one `com.typesafe.config.Config` parameter.
+      class = ""
 
       # Dispatcher for the plugin actor.
       plugin-dispatcher = "akka.persistence.dispatchers.default-plugin-dispatcher"
@@ -124,6 +134,13 @@ akka.persistence {
     # Fallback settings for snapshot store plugin configurations
     # These settings are used if they are not defined in plugin config section.
     snapshot-store-plugin-fallback {
+    
+      # Fully qualified class name providing snapshot store plugin api 
+      # implementation. It is mandatory to specify this property if
+      # snapshot store is enabled.
+      # The class must have a constructor without parameters or constructor with
+      # one `com.typesafe.config.Config` parameter.
+      class = ""
 
       # Dispatcher for the plugin actor.
       plugin-dispatcher = "akka.persistence.dispatchers.default-plugin-dispatcher"
@@ -177,7 +194,8 @@ akka.persistence.snapshot-store.local {
     dir = "snapshots"
     # Number load attempts when recovering from the latest snapshot fails
     # yet older snapshot files are available. Each recovery attempt will try
-    # to recover using an older than previously failed-on snapshot file (if any are present).
+    # to recover using an older than previously failed-on snapshot file 
+    # (if any are present).
     max-load-attempts = 3
 }
 

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

@@ -253,7 +253,11 @@ class Persistence(val system: ExtendedActorSystem) extends Extension {
 
   private def createPlugin(configPath: String, pluginConfig: Config): ActorRef = {
     val pluginActorName = configPath
-    val pluginClassName = pluginConfig.getString("class")
+    val pluginClassName = pluginConfig.getString("class") match {
+      case "" ⇒ throw new IllegalArgumentException("Plugin class name must be defined in config property " +
+        s"[$configPath.class]")
+      case className ⇒ className
+    }
     log.debug(s"Create plugin: $pluginActorName $pluginClassName")
     val pluginClass = system.dynamicAccess.getClassFor[Any](pluginClassName).get
     val pluginDispatcherId = pluginConfig.getString("plugin-dispatcher")