diff --git a/akka-docs/rst/java/lambda-persistence.rst b/akka-docs/rst/java/lambda-persistence.rst index 0f568410b0..24c3c01919 100644 --- a/akka-docs/rst/java/lambda-persistence.rst +++ b/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:: + + + 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:: ../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 ==================== diff --git a/akka-docs/rst/java/persistence.rst b/akka-docs/rst/java/persistence.rst index ca17bf366d..737e00b6e6 100644 --- a/akka-docs/rst/java/persistence.rst +++ b/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:: + + + 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:: ../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 ==================== diff --git a/akka-docs/rst/scala/code/docs/persistence/PersistencePluginDocSpec.scala b/akka-docs/rst/scala/code/docs/persistence/PersistencePluginDocSpec.scala index c1e1705602..b0881583ff 100644 --- a/akka-docs/rst/scala/code/docs/persistence/PersistencePluginDocSpec.scala +++ b/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" diff --git a/akka-docs/rst/scala/persistence.rst b/akka-docs/rst/scala/persistence.rst index 61229da62f..8a48bd0581 100644 --- a/akka-docs/rst/scala/persistence.rst +++ b/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 diff --git a/akka-persistence/src/main/resources/reference.conf b/akka-persistence/src/main/resources/reference.conf index 6c439ec826..1b1d995732 100644 --- a/akka-persistence/src/main/resources/reference.conf +++ b/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: -# `class` : Fully qualified class name providing journal-plugin-api or snapshot-store-plugin-api implementation, -# 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/ +# 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. - # Persistent actor or view can override `journalPluginId` method in order to rely on a different journal plugin. + # Absolute path to the journal plugin configuration entry used by + # 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. - # Persistent actor or view can override `snapshotPluginId` method in order to rely on a different snapshot plugin. + # Absolute path to the snapshot plugin configuration entry used by + # 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 } diff --git a/akka-persistence/src/main/scala/akka/persistence/Persistence.scala b/akka-persistence/src/main/scala/akka/persistence/Persistence.scala index de476e26ae..5453c098d4 100644 --- a/akka-persistence/src/main/scala/akka/persistence/Persistence.scala +++ b/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")