!per #15230 rename processorId => persistentId
* This is NOT binary compatible, we're in an *experimental* module. * disabled binary compat checks for package akka.persistence * Source compatibility is retained, but users should migrate do the new method name ASAP. * Plugin APIs were migrated in a way that allows the old plugins to compile agains 2.3.4 without having to change anything. Hopefuly this will help authors migrate to 2.3.4 sooner. This is only source level compatible, not binary compatible. * added deprecation warnings on all processorId methods and provided bridges where possible * for users, the migration should be painless, they can still override the old method, and it'll work. But we encourage them to move to persistenceId; All delegation code will have to be removed afterwards ofc. Conflicts: akka-persistence/src/main/scala/akka/persistence/Channel.scala akka-persistence/src/main/scala/akka/persistence/JournalProtocol.scala akka-persistence/src/main/scala/akka/persistence/Persistent.scala akka-persistence/src/main/scala/akka/persistence/PersistentChannel.scala akka-persistence/src/main/scala/akka/persistence/Processor.scala akka-persistence/src/main/scala/akka/persistence/Snapshot.scala akka-persistence/src/main/scala/akka/persistence/journal/AsyncWriteProxy.scala akka-persistence/src/main/scala/akka/persistence/journal/inmem/InmemJournal.scala akka-persistence/src/main/scala/akka/persistence/journal/leveldb/LeveldbKey.scala akka-persistence/src/main/scala/akka/persistence/snapshot/SnapshotStore.scala akka-persistence/src/test/scala/akka/persistence/serialization/SerializerSpec.scala project/AkkaBuild.scala
This commit is contained in:
Konrad 'ktoso' Malawski
parent
c8406e3466
commit
4bb321a83a
58 changed files with 502 additions and 435 deletions
|
|
@ -22,9 +22,9 @@ public class PersistenceDocTest {
|
|||
public interface SomeOtherMessage {}
|
||||
|
||||
public interface ProcessorMethods {
|
||||
//#processor-id
|
||||
public String processorId();
|
||||
//#processor-id
|
||||
//#persistence-id
|
||||
public String persistenceId();
|
||||
//#persistence-id
|
||||
//#recovery-status
|
||||
public boolean recoveryRunning();
|
||||
public boolean recoveryFinished();
|
||||
|
|
@ -120,12 +120,12 @@ public class PersistenceDocTest {
|
|||
}
|
||||
|
||||
class MyProcessor4 extends UntypedProcessor implements ProcessorMethods {
|
||||
//#processor-id-override
|
||||
//#persistence-id-override
|
||||
@Override
|
||||
public String processorId() {
|
||||
return "my-stable-processor-id";
|
||||
public String persistenceId() {
|
||||
return "my-stable-persistence-id";
|
||||
}
|
||||
//#processor-id-override
|
||||
//#persistence-id-override
|
||||
@Override
|
||||
public void onReceive(Object message) throws Exception {}
|
||||
}
|
||||
|
|
@ -488,8 +488,8 @@ public class PersistenceDocTest {
|
|||
//#view
|
||||
class MyView extends UntypedView {
|
||||
@Override
|
||||
public String processorId() {
|
||||
return "some-processor-id";
|
||||
public String persistenceId() {
|
||||
return "some-persistence-id";
|
||||
}
|
||||
|
||||
@Override
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ public class PersistencePluginDocTest {
|
|||
|
||||
class MySnapshotStore extends SnapshotStore {
|
||||
@Override
|
||||
public Future<Option<SelectedSnapshot>> doLoadAsync(String processorId, SnapshotSelectionCriteria criteria) {
|
||||
public Future<Option<SelectedSnapshot>> doLoadAsync(String persistenceId, SnapshotSelectionCriteria criteria) {
|
||||
return null;
|
||||
}
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ public class PersistencePluginDocTest {
|
|||
}
|
||||
|
||||
@Override
|
||||
public void doDelete(String processorId, SnapshotSelectionCriteria criteria) throws Exception {
|
||||
public void doDelete(String persistenceId, SnapshotSelectionCriteria criteria) throws Exception {
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -87,22 +87,22 @@ public class PersistencePluginDocTest {
|
|||
}
|
||||
|
||||
@Override
|
||||
public Future<Void> doAsyncDeleteMessages(Iterable<PersistentId> messageIds, boolean permanent) {
|
||||
public Future<Void> doAsyncDeleteMessages(Iterable<PersistenceId> messageIds, boolean permanent) {
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Future<Void> doAsyncDeleteMessagesTo(String processorId, long toSequenceNr, boolean permanent) {
|
||||
public Future<Void> doAsyncDeleteMessagesTo(String persistenceId, long toSequenceNr, boolean permanent) {
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Future<Void> doAsyncReplayMessages(String processorId, long fromSequenceNr, long toSequenceNr, long max, Procedure<PersistentRepr> replayCallback) {
|
||||
public Future<Void> doAsyncReplayMessages(String persistenceId, long fromSequenceNr, long toSequenceNr, long max, Procedure<PersistentRepr> replayCallback) {
|
||||
return null;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Future<Long> doAsyncReadHighestSequenceNr(String processorId, long fromSequenceNr) {
|
||||
public Future<Long> doAsyncReadHighestSequenceNr(String persistenceId, long fromSequenceNr) {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -161,30 +161,30 @@ Identifiers
|
|||
-----------
|
||||
|
||||
A processor must have an identifier that doesn't change across different actor incarnations. It defaults to the
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``processorId``
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``persistenceId``
|
||||
method.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#processor-id
|
||||
.. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#persistence-id
|
||||
|
||||
Applications can customize a processor's id by specifying an actor name during processor creation as shown in
|
||||
section :ref:`processors-java`. This changes that processor's name in its actor hierarchy and hence influences only
|
||||
part of the processor id. To fully customize a processor's id, the ``processorId`` method must be overridden.
|
||||
part of the processor id. To fully customize a processor's id, the ``persistenceId`` method must be overridden.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#processor-id-override
|
||||
.. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#persistence-id-override
|
||||
|
||||
Overriding ``processorId`` is the recommended way to generate stable identifiers.
|
||||
Overriding ``persistenceId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
.. _views-java-lambda:
|
||||
|
||||
Views
|
||||
=====
|
||||
|
||||
Views can be implemented by extending the ``AbstractView`` abstract class, implement the ``processorId`` method
|
||||
Views can be implemented by extending the ``AbstractView`` abstract class, implement the ``persistenceId`` method
|
||||
and setting the “initial behavior” in the constructor by calling the :meth:`receive` method.
|
||||
|
||||
.. includecode:: ../../../akka-samples/akka-sample-persistence-java-lambda/src/main/java/doc/LambdaPersistenceDocTest.java#view
|
||||
|
||||
The ``processorId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
The ``persistenceId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
the referenced processor is actually running. Views read messages from a processor's journal directly. When a
|
||||
processor is started later and begins to write new messages, the corresponding view is updated automatically, by
|
||||
default.
|
||||
|
|
@ -234,7 +234,7 @@ Applications can customize a view's id by specifying an actor name during view c
|
|||
name in its actor hierarchy and hence influences only part of the view id. To fully customize a view's id, the
|
||||
``viewId`` method must be overridden. Overriding ``viewId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
The ``viewId`` must differ from the referenced ``processorId``, unless :ref:`snapshots-java` of a view and its
|
||||
The ``viewId`` must differ from the referenced ``persistenceId``, unless :ref:`snapshots-java` of a view and its
|
||||
processor shall be shared (which is what applications usually do not want).
|
||||
|
||||
.. _channels-java-lambda:
|
||||
|
|
|
|||
|
|
@ -175,30 +175,30 @@ Identifiers
|
|||
-----------
|
||||
|
||||
A processor must have an identifier that doesn't change across different actor incarnations. It defaults to the
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``processorId``
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``persistenceId``
|
||||
method.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocTest.java#processor-id
|
||||
.. includecode:: code/docs/persistence/PersistenceDocTest.java#persistence-id
|
||||
|
||||
Applications can customize a processor's id by specifying an actor name during processor creation as shown in
|
||||
section :ref:`processors-java`. This changes that processor's name in its actor hierarchy and hence influences only
|
||||
part of the processor id. To fully customize a processor's id, the ``processorId`` method must be overridden.
|
||||
part of the processor id. To fully customize a processor's id, the ``persistenceId`` method must be overridden.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocTest.java#processor-id-override
|
||||
.. includecode:: code/docs/persistence/PersistenceDocTest.java#persistence-id-override
|
||||
|
||||
Overriding ``processorId`` is the recommended way to generate stable identifiers.
|
||||
Overriding ``persistenceId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
.. _views-java:
|
||||
|
||||
Views
|
||||
=====
|
||||
|
||||
Views can be implemented by extending the ``UntypedView`` trait and implementing the ``onReceive`` and the ``processorId``
|
||||
Views can be implemented by extending the ``UntypedView`` trait and implementing the ``onReceive`` and the ``persistenceId``
|
||||
methods.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocTest.java#view
|
||||
|
||||
The ``processorId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
The ``persistenceId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
the referenced processor is actually running. Views read messages from a processor's journal directly. When a
|
||||
processor is started later and begins to write new messages, the corresponding view is updated automatically, by
|
||||
default.
|
||||
|
|
@ -248,7 +248,7 @@ Applications can customize a view's id by specifying an actor name during view c
|
|||
name in its actor hierarchy and hence influences only part of the view id. To fully customize a view's id, the
|
||||
``viewId`` method must be overridden. Overriding ``viewId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
The ``viewId`` must differ from the referenced ``processorId``, unless :ref:`snapshots-java` of a view and its
|
||||
The ``viewId`` must differ from the referenced ``persistenceId``, unless :ref:`snapshots-java` of a view and its
|
||||
processor shall be shared (which is what applications usually do not want).
|
||||
|
||||
.. _channels-java:
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ Processors
|
|||
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.
|
||||
- :ref:`persistence-identifiers` are of type ``String``, have a default value and can be overridden by applications.
|
||||
- Supports :ref:`batch-writes`.
|
||||
- Supports stashing of messages.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,42 @@ To extend ``PersistentActor``::
|
|||
|
||||
class NewPersistentProcessor extends PersistentActor { /*...*/ }
|
||||
|
||||
No other API changes are required for this migration.
|
||||
|
||||
Renamed processorId to persistenceId
|
||||
====================================
|
||||
In Akka Persistence ``2.3.3`` and previously, the main building block of applications were Processors.
|
||||
Persistent messages, as well as processors implemented the ``processorId`` method to identify which persistent entity a message belonged to.
|
||||
|
||||
This concept remains the same in Akka ``2.3.4``, yet we rename ``processorId`` to ``persistenceId`` because Processors will be removed,
|
||||
and persistent messages can be used from different classes not only ``PersistentActor`` (Views, directly from Journals etc).
|
||||
|
||||
We provided the renamed method also on already deprecated classes (Channels), so you can simply apply a global rename of ``processorId`` to ``persistenceId``.
|
||||
|
||||
Plugin APIs: Renamed PersistentId to PersistenceId
|
||||
==================================================
|
||||
Following the removal of Processors and moving to ``persistenceId``, the plugin SPI visible type has changed.
|
||||
The move from ``2.3.3`` to ``2.3.4`` should be relatively painless, and plugins will work even when using the deprecated ``PersistentId`` type.
|
||||
|
||||
Change your implementations from::
|
||||
|
||||
def asyncWriteMessages(messages: immutable.Seq[PersistentRepr]): Future[Unit] = // ...
|
||||
|
||||
def asyncDeleteMessages(messageIds: immutable.Seq[PersistentId], permanent: Boolean): Future[Unit] = {
|
||||
val p = messageIds.head.processorId // old
|
||||
// ...
|
||||
}
|
||||
|
||||
to::
|
||||
|
||||
def asyncWriteMessages(messages: immutable.Seq[PersistentRepr]): Future[Unit] = // ...
|
||||
|
||||
def asyncDeleteMessages(messageIds: immutable.Seq[PersistenceId], permanent: Boolean): Future[Unit] = {
|
||||
val p = messageIds.head.persistenceId // new
|
||||
// ...
|
||||
}
|
||||
|
||||
Plugins written for ``2.3.3`` are source level compatible with ``2.3.4``, using the deprecated types, but will not work with future releases.
|
||||
Plugin maintainers are asked to update their plugins to ``2.3.4`` as soon as possible.
|
||||
|
||||
Removed Processor in favour of extending PersistentActor with persistAsync
|
||||
==========================================================================
|
||||
|
|
|
|||
|
|
@ -111,9 +111,9 @@ trait PersistenceDocSpec {
|
|||
|
||||
new AnyRef {
|
||||
trait ProcessorMethods {
|
||||
//#processor-id
|
||||
def processorId: String
|
||||
//#processor-id
|
||||
//#persistence-id
|
||||
def persistenceId: String
|
||||
//#persistence-id
|
||||
//#recovery-status
|
||||
def recoveryRunning: Boolean
|
||||
def recoveryFinished: Boolean
|
||||
|
|
@ -123,9 +123,9 @@ trait PersistenceDocSpec {
|
|||
//#current-message
|
||||
}
|
||||
class MyProcessor1 extends Processor with ProcessorMethods {
|
||||
//#processor-id-override
|
||||
override def processorId = "my-stable-processor-id"
|
||||
//#processor-id-override
|
||||
//#persistence-id-override
|
||||
override def persistenceId = "my-stable-persistence-id"
|
||||
//#persistence-id-override
|
||||
def receive = {
|
||||
case _ =>
|
||||
}
|
||||
|
|
@ -411,7 +411,7 @@ trait PersistenceDocSpec {
|
|||
|
||||
//#view
|
||||
class MyView extends View {
|
||||
def processorId: String = "some-processor-id"
|
||||
override def persistenceId: String = "some-persistence-id"
|
||||
|
||||
def receive: Actor.Receive = {
|
||||
case Persistent(payload, sequenceNr) => // ...
|
||||
|
|
@ -440,26 +440,26 @@ trait PersistenceDocSpec {
|
|||
|
||||
val materializer = FlowMaterializer(MaterializerSettings())
|
||||
|
||||
val flow: Flow[Persistent] = PersistentFlow.fromProcessor("some-processor-id")
|
||||
val flow: Flow[Persistent] = PersistentFlow.fromPersistence("some-persistence-id")
|
||||
val producer: Producer[Persistent] = flow.toProducer(materializer)
|
||||
//#producer-creation
|
||||
|
||||
//#producer-buffer-size
|
||||
PersistentFlow.fromProcessor("some-processor-id", PersistentPublisherSettings(maxBufferSize = 200))
|
||||
PersistentFlow.fromPersistence("some-persistence-id", PersistentPublisherSettings(maxBufferSize = 200))
|
||||
//#producer-buffer-size
|
||||
|
||||
//#producer-examples
|
||||
// 1 producer and 2 consumers:
|
||||
val producer1: Producer[Persistent] =
|
||||
PersistentFlow.fromProcessor("processor-1").toProducer(materializer)
|
||||
PersistentFlow.fromPersistence("processor-1").toProducer(materializer)
|
||||
Flow(producer1).foreach(p => println(s"consumer-1: ${p.payload}")).consume(materializer)
|
||||
Flow(producer1).foreach(p => println(s"consumer-2: ${p.payload}")).consume(materializer)
|
||||
|
||||
// 2 producers (merged) and 1 consumer:
|
||||
val producer2: Producer[Persistent] =
|
||||
PersistentFlow.fromProcessor("processor-2").toProducer(materializer)
|
||||
PersistentFlow.fromPersistence("processor-2").toProducer(materializer)
|
||||
val producer3: Producer[Persistent] =
|
||||
PersistentFlow.fromProcessor("processor-3").toProducer(materializer)
|
||||
PersistentFlow.fromPersistence("processor-3").toProducer(materializer)
|
||||
Flow(producer2).merge(producer3).foreach { p =>
|
||||
println(s"consumer-3: ${p.payload}")
|
||||
}.consume(materializer)
|
||||
|
|
|
|||
|
|
@ -126,16 +126,16 @@ trait SharedLeveldbPluginDocSpec {
|
|||
class MyJournal extends AsyncWriteJournal {
|
||||
def asyncWriteMessages(messages: Seq[PersistentRepr]): Future[Unit] = ???
|
||||
def asyncWriteConfirmations(confirmations: Seq[PersistentConfirmation]): Future[Unit] = ???
|
||||
def asyncDeleteMessages(messageIds: Seq[PersistentId], permanent: Boolean): Future[Unit] = ???
|
||||
def asyncDeleteMessagesTo(processorId: String, toSequenceNr: Long, permanent: Boolean): Future[Unit] = ???
|
||||
def asyncReplayMessages(processorId: String, fromSequenceNr: Long, toSequenceNr: Long, max: Long)(replayCallback: (PersistentRepr) => Unit): Future[Unit] = ???
|
||||
def asyncReadHighestSequenceNr(processorId: String, fromSequenceNr: Long): Future[Long] = ???
|
||||
def asyncDeleteMessages(messageIds: Seq[PersistenceId], permanent: Boolean): Future[Unit] = ???
|
||||
def asyncDeleteMessagesTo(persistenceId: String, toSequenceNr: Long, permanent: Boolean): Future[Unit] = ???
|
||||
def asyncReplayMessages(persistenceId: String, fromSequenceNr: Long, toSequenceNr: Long, max: Long)(replayCallback: (PersistentRepr) => Unit): Future[Unit] = ???
|
||||
def asyncReadHighestSequenceNr(persistenceId: String, fromSequenceNr: Long): Future[Long] = ???
|
||||
}
|
||||
|
||||
class MySnapshotStore extends SnapshotStore {
|
||||
def loadAsync(processorId: String, criteria: SnapshotSelectionCriteria): Future[Option[SelectedSnapshot]] = ???
|
||||
def loadAsync(persistenceId: String, criteria: SnapshotSelectionCriteria): Future[Option[SelectedSnapshot]] = ???
|
||||
def saveAsync(metadata: SnapshotMetadata, snapshot: Any): Future[Unit] = ???
|
||||
def saved(metadata: SnapshotMetadata): Unit = ???
|
||||
def delete(metadata: SnapshotMetadata): Unit = ???
|
||||
def delete(processorId: String, criteria: SnapshotSelectionCriteria): Unit = ???
|
||||
def delete(persistenceId: String, criteria: SnapshotSelectionCriteria): Unit = ???
|
||||
}
|
||||
|
|
|
|||
|
|
@ -165,30 +165,30 @@ Identifiers
|
|||
-----------
|
||||
|
||||
A processor must have an identifier that doesn't change across different actor incarnations. It defaults to the
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``processorId``
|
||||
``String`` representation of processor's path without the address part and can be obtained via the ``persistenceId``
|
||||
method.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#processor-id
|
||||
.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#persistence-id
|
||||
|
||||
Applications can customize a processor's id by specifying an actor name during processor creation as shown in
|
||||
section :ref:`processors`. This changes that processor's name in its actor hierarchy and hence influences only
|
||||
part of the processor id. To fully customize a processor's id, the ``processorId`` method must be overridden.
|
||||
part of the processor id. To fully customize a processor's id, the ``persistenceId`` method must be overridden.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#processor-id-override
|
||||
.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#persistence-id-override
|
||||
|
||||
Overriding ``processorId`` is the recommended way to generate stable identifiers.
|
||||
Overriding ``persistenceId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
.. _views:
|
||||
|
||||
Views
|
||||
=====
|
||||
|
||||
Views can be implemented by extending the ``View`` trait and implementing the ``receive`` and the ``processorId``
|
||||
Views can be implemented by extending the ``View`` trait and implementing the ``receive`` and the ``persistenceId``
|
||||
methods.
|
||||
|
||||
.. includecode:: code/docs/persistence/PersistenceDocSpec.scala#view
|
||||
|
||||
The ``processorId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
The ``persistenceId`` identifies the processor from which the view receives journaled messages. It is not necessary
|
||||
the referenced processor is actually running. Views read messages from a processor's journal directly. When a
|
||||
processor is started later and begins to write new messages, the corresponding view is updated automatically, by
|
||||
default.
|
||||
|
|
@ -238,7 +238,7 @@ Applications can customize a view's id by specifying an actor name during view c
|
|||
name in its actor hierarchy and hence influences only part of the view id. To fully customize a view's id, the
|
||||
``viewId`` method must be overridden. Overriding ``viewId`` is the recommended way to generate stable identifiers.
|
||||
|
||||
The ``viewId`` must differ from the referenced ``processorId``, unless :ref:`snapshots` of a view and its
|
||||
The ``viewId`` must differ from the referenced ``persistenceId``, unless :ref:`snapshots` of a view and its
|
||||
processor shall be shared (which is what applications usually do not want).
|
||||
|
||||
.. _channels:
|
||||
|
|
@ -378,7 +378,7 @@ 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:
|
||||
.. _persistence-identifiers:
|
||||
|
||||
Identifiers
|
||||
-----------
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue