diff --git a/akka-docs/rst/java/persistence.rst b/akka-docs/rst/java/persistence.rst index b031954447..43f1d2603b 100644 --- a/akka-docs/rst/java/persistence.rst +++ b/akka-docs/rst/java/persistence.rst @@ -20,8 +20,9 @@ communication channels with at-least-once message delivery semantics. changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the contents of the ``akka.persistence`` package. -Akka persistence is inspired by the `eventsourced`_ library. It follows the same concepts and architecture of -`eventsourced`_ but significantly differs on API and implementation level. +Akka persistence is inspired by and the official replacement of the `eventsourced`_ library. It follows the same +concepts and architecture of `eventsourced`_ but significantly differs on API and implementation level. See also +:ref:`migration-eventsourced-2.3` .. _eventsourced: https://github.com/eligosource/eventsourced diff --git a/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst b/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst new file mode 100644 index 0000000000..ee159b9bdb --- /dev/null +++ b/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst @@ -0,0 +1,217 @@ +.. _migration-eventsourced-2.3: + +####################################################### + Migration Guide Eventsourced to Akka Persistence 2.3.x +####################################################### + +General notes +============= + +`Eventsourced`_ and Akka :ref:`persistence-scala` share many high-level concepts but strongly differ on design, +implementation and usage level. This migration guide is more a higher-level comparison of Eventsourced and Akka +Persistence rather than a sequence of low-level instructions how to transform Eventsourced application code into +Akka Persistence application code. This should provide a good starting point for a migration effort. Development +teams should consult the user documentation of both projects for further details. + +.. _Eventsourced: https://github.com/eligosource/eventsourced + +Scope of this migration guide is code migration, not journal migration. Journals written by Eventsourced can neither +be used directly Akka Persistence nor migrated to Akka Persistence compatible journals. Journal migration tools may +be provided in the future but do not exist at the moment. + +Extensions +========== + +Eventsourced and Akka Persistence are both :ref:`extending-akka-scala`. + +**Eventsourced:** ``EventsourcingExtension`` + +- Must be explicitly created with an actor system and an application-defined journal actor as arguments. + (see `usage example `_). +- `Processors `_ and + `Channels `_ + must be created with the factory methods ``processorOf`` and ``channelOf`` defined on ``EventsourcingExtension``. +- Is a central registry of created processors and channels. + +**Akka Persistence:** ``Persistence`` extension + +- Must **not** be explicitly created by an application. A ``Persistence`` extension is implicitly created upon first + processor or channel creation. Journal actors are automatically created from a journal plugin configuration (see + :ref:`journal-plugin-api`). +- :ref:`processors` and :ref:`channels` can be created like any other actor with ``actorOf`` without using the + ``Persistence`` extension. +- Is **not** a central registry of processors and channels. + +Processors +========== + +**Eventsourced:** ``Eventsourced`` + +- Stackable trait that adds journaling (write-ahead-logging) to actors (see processor + `definition `_ and + `creation `_). + Name ``Eventsourced`` caused some confusion in the past as many examples used ``Eventsourced`` processors + for *command sourcing*. See also + `this FAQ entry `_ for + clarification. +- Must be explicitly `recovered `_ using recovery methods + on ``EventsourcingExtension``. Applications are responsible for avoiding an interference of replayed messages + and new messages i.e. applications have to explicitly wait for recovery to complete. Recovery on processor + re-start is not supported out-of-the box. +- Journaling-preserving `behavior changes `_ are + only possible with special-purpose methods ``become`` and ``unbecome``, in addition to non-journaling-preserving + behavior changes with default methods ``context.become`` and ``context.unbecome``. +- Writes messages of type ``Message`` to the journal (see processor + `usage `_). + `Sender references `_ + are not stored in the journal i.e. the sender reference of a replayed message is always ``system.deadLetters``. +- Supports `snapshots `_. +- Identifiers are of type ``Int`` and must be application-defined. +- Does not support batch-writes of messages to the journal. +- Does not support stashing of messages. + +**Akka Persistence:** ``Processor`` + +- Trait that adds journaling (write-ahead-logging) to actors (see :ref:`processors`) and used by applications for + *command sourcing*. Corresponds to ``Eventsourced`` processors in Eventsourced but is not a stackable trait. +- Automatically recovers on start and re-start, by default. :ref:`recovery` can be customized or turned off by + overriding actor life cycle hooks ``preStart`` and ``preRestart``. ``Processor`` takes care that new messages + never interfere with replayed messages. New messages are internally buffered until recovery completes. +- No special-purpose behavior change methods. Default behavior change methods ``context.become`` and + ``context.unbecome`` can be used and are journaling-preserving. +- Writes messages of type ``Persistent`` to the journal (see :ref:`persistent-messages`). Corresponds to ``Message`` + in Eventsourced. Sender references are written to the journal. A reply to senders must therefore be done via a + channel in order to avoid redundant replies during replay. Sender references of type ``PromiseActorRef`` are + not journaled, they are ``system.deadLetters`` on replay. +- Supports :ref:`snapshots`. +- :ref:`processor-identifiers` are of type ``String``, have a default value and can be overridden by applications. +- Supports :ref:`batch-writes`. +- Supports stashing of messages. + +**Akka Persistence:** ``EventsourcedProcessor`` + +- Extension trait and pattern on top of ``Processor`` to support :ref:`event-sourcing`. Has no direct counterpart in + Eventsourced. Can be considered as a replacement of two processors in Eventsourced where one processor processes + commands and the other processes events that have been emitted by the command processor. + +Channels +======== + +**Eventsourced:** ``DefaultChannel`` + +- Prevents redundant delivery of messages to a destination (see + `usage example `_ and + `default channel `_). +- Is associated with a single destination actor reference. A new incarnation of the destination is not automatically + resolved by the channel. In this case a new channel must be created. +- Must be explicitly activated using methods ``deliver`` or ``recover`` defined on ``EventsourcingExtension``. +- Must be activated **after** all processors have been activated. Depending on the + `recovery `_ method, this is either done automatically or must + be followed by the application (see `non-blocking recovery `_). + This is necessary for a network of processors and channels to recover consistently. +- Does not redeliver messages on missing or negative delivery confirmation. +- Cannot be used standalone. + +**Akka Persistence:** ``Channel`` + +- Prevents redundant delivery of messages to a destination (see :ref:`channels`) i.e. serves the same primary purpose + as in Eventsourced. +- Is not associated with a single destination. A destination can be specified with each ``Deliver`` request and is + referred to by an actor path. A destination path is resolved to the current destination incarnation during delivery + (via ``actorSelection``). +- Must not be explicitly activated. Also, a network of processors and channels automatically recover consistently, + even if they are distributed. This enhancement, together with improved processor recovery, makes recovery of complex + Akka Persistence applications trivial. No special recovery procedures must be run by applications. +- Redelivers messages on missing delivery confirmation (see :ref:`redelivery`). In contrast to Eventsourced, Akka + Persistence doesn't distinguish between missing and negative confirmations. It only has a notion of missing + confirmations using timeouts (which are closely related to negative confirmations as both trigger message + redelivery). +- Can be used standalone. + +Persistent channels +=================== + +**Eventsourced:** ``ReliableChannel`` + +- Provides ``DefaultChannel`` functionality plus persistence and recovery from sender JVM crashes (see `ReliableChannel + `_). Also provides message redelivery in case of missing + or negative delivery confirmations. +- Delivers next message to a destination only if previous message has been successfully delivered (flow control is + done by destination). +- Stops itself when the maximum number of redelivery attempts has been reached. +- Cannot reply on persistence. +- Can be used standalone. + +**Akka Persistence:** ``PersistentChannel`` + +- Provides ``Channel`` functionality plus persistence and recovery from sender JVM crashes (see + :ref:`persistent-channels`). Same message redelivery features as ``Channel``. +- Redelivers unconfirmed messages concurrently to newly delivered messages. Flow control is done by channel using + a configurable minimum and maximum number of pending confirmations. +- Optionally notifies applications about messages for which the maximum number of delivery attempts has been reached + (also offered by ``Channel``). +- Can reply on persistence (= accept acknowledgement). +- Can be used standalone. + +Views +===== + +**Eventsourced:** + +- No direct support for views. Only way to maintain a view is to use a channel and a processor as destination. + +**Akka Persistence:** ``View`` + +- Receives the message stream written by a ``Processor`` or ``EventsourcedProcessor`` by reading it directly from the + journal (see :ref:`views`). Alternative to using channels. Useful in situations where actors shall receive a + persistent message stream in correct order without duplicates. +- Can be used in combination with :ref:`channels` for sending messages. +- Supports :ref:`snapshots`. + +Serializers +=========== + +**Eventsourced:** + +- Uses a protobuf serializer for serializing ``Message`` objects. +- Delegates to a configurable Akka serializer for serializing ``Message`` payloads. +- Delegates to a configurable, proprietary (stream) serializer for serializing snapshots. +- See `Serialization `_. + +**Akka Persistence:** + +- Uses a protobuf serializer for serializing ``Persistent`` objects. +- Delegates to a configurable Akka serializer for serializing ``Persistent`` payloads. +- Delegates to a configurable Akka serializer for serializing snapshots. +- See :ref:`custom-serialization`. + +Sequence numbers +================ + +**Eventsourced:** + +- Generated on a per-journal basis. + +**Akka Persistence:** + +- Generated on a per-processor basis. + +Storage plugins +=============== + +**Eventsourced:** + +- Plugin API: + `SynchronousWriteReplaySupport `_ and + `AsynchronousWriteReplaySupport `_ +- No separation between journal and snapshot storage plugins. +- All plugins pre-packaged with project (see `journals `_ and + `snapshot configuration `_) + +**Akka Persistence:** + +- Plugin API: ``SyncWriteJournal``, ``AsyncWriteJournal``, ``AsyncRecovery``, ``SnapshotStore`` + (see :ref:`storage-plugins`). +- Clear separation between journal and snapshot storage plugins. +- Limited number of :ref:`pre-packaged-plugins` (LevelDB journal and local snapshot store). +- Impressive list of `community plugins `_. diff --git a/akka-docs/rst/project/migration-guides.rst b/akka-docs/rst/project/migration-guides.rst index 2e7d913941..352bccece6 100644 --- a/akka-docs/rst/project/migration-guides.rst +++ b/akka-docs/rst/project/migration-guides.rst @@ -10,3 +10,4 @@ Migration Guides migration-guide-2.0.x-2.1.x migration-guide-2.1.x-2.2.x migration-guide-2.2.x-2.3.x + migration-guide-eventsourced-2.3.x diff --git a/akka-docs/rst/scala/persistence.rst b/akka-docs/rst/scala/persistence.rst index bfea346684..eaf68d4dca 100644 --- a/akka-docs/rst/scala/persistence.rst +++ b/akka-docs/rst/scala/persistence.rst @@ -21,7 +21,8 @@ communication channels with at-least-once message delivery semantics. contents of the ``akka.persistence`` package. Akka persistence is inspired by and the official replacement of the `eventsourced`_ library. It follows the same -concepts and architecture of `eventsourced`_ but significantly differs on API and implementation level. +concepts and architecture of `eventsourced`_ but significantly differs on API and implementation level. See also +:ref:`migration-eventsourced-2.3` .. _eventsourced: https://github.com/eligosource/eventsourced @@ -81,6 +82,8 @@ A ``Processor`` itself is an ``Actor`` and can therefore be instantiated with `` .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#usage +.. _recovery: + Recovery -------- @@ -295,6 +298,8 @@ If an application wants to have more control how sequence numbers are assigned t application-specific sequence number generator and include the generated sequence numbers into the ``payload`` of ``Persistent`` messages. +.. _persistent-channels: + Persistent channels ------------------- @@ -333,6 +338,8 @@ creating the channel with the ``replyPersistent`` configuration parameter set to With this setting, either the successfully persisted message is replied to the sender or a ``PersistenceFailure`` message. In case the latter case, the sender should re-send the message. +.. _processor-identifiers: + Identifiers ----------- @@ -344,6 +351,8 @@ a channel identifier, it should be provided as argument ``Channel.props(String)` .. includecode:: code/docs/persistence/PersistenceDocSpec.scala#channel-id-override +.. _persistent-messages: + Persistent messages =================== @@ -490,6 +499,8 @@ In larger integration scenarios, channel destinations may be actors that submit message broker, for example. After having successfully submitted an event, they should call ``confirm()`` on the received ``ConfirmablePersistent`` message. +.. _batch-writes: + Batch writes ============ @@ -520,6 +531,8 @@ Confirmation and deletion operations performed by :ref:`channels` are also batch and deletion batch sizes are configurable with ``akka.persistence.journal.max-confirmation-batch-size`` and ``akka.persistence.journal.max-deletion-batch-size``, respectively. +.. _storage-plugins: + Storage plugins =============== @@ -531,6 +544,8 @@ imports: .. includecode:: code/docs/persistence/PersistencePluginDocSpec.scala#plugin-imports +.. _journal-plugin-api: + Journal plugin API ------------------ @@ -571,6 +586,8 @@ 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: + Pre-packaged plugins ==================== @@ -635,6 +652,8 @@ directory. This can be changed by configuration where the specified path can be .. includecode:: code/docs/persistence/PersistencePluginDocSpec.scala#snapshot-config +.. _custom-serialization: + Custom serialization ====================