From 15828db19f6bef501f214e68e7705dd9909f6701 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Thu, 13 Aug 2015 20:19:04 +0200 Subject: [PATCH] =per #18123 Deprecate PersistentView * marked PersistentFSM as experimental * also changed the order of some sections in migration guide * link to 2.2->2.3 migration guide * update experimental index page --- akka-docs/rst/experimental/index-java.rst | 2 +- akka-docs/rst/experimental/index.rst | 4 +- akka-docs/rst/java/lambda-persistence.rst | 26 ++ akka-docs/rst/java/persistence.rst | 19 ++ akka-docs/rst/java/untyped-actors.rst | 2 + .../project/migration-guide-2.2.x-2.3.x.rst | 257 +----------------- .../project/migration-guide-2.3.x-2.4.x.rst | 152 ++++++----- akka-docs/rst/scala/actors.rst | 2 + akka-docs/rst/scala/persistence.rst | 26 ++ .../akka/persistence/PersistentView.scala | 4 + .../akka/persistence/fsm/PersistentFSM.scala | 2 + .../persistence/fsm/PersistentFSMBase.scala | 4 +- 12 files changed, 175 insertions(+), 325 deletions(-) diff --git a/akka-docs/rst/experimental/index-java.rst b/akka-docs/rst/experimental/index-java.rst index 52653921aa..c2d8e70186 100644 --- a/akka-docs/rst/experimental/index-java.rst +++ b/akka-docs/rst/experimental/index-java.rst @@ -19,10 +19,10 @@ prior deprecation. .. toctree:: :maxdepth: 1 - ../java/persistence ../dev/multi-node-testing ../java/lambda-actors ../java/lambda-fsm + ../java/persistence-query Another reason for marking a module as experimental is that it's too early to tell if the module has a maintainer that can take the responsibility diff --git a/akka-docs/rst/experimental/index.rst b/akka-docs/rst/experimental/index.rst index 8b2bae6a4e..f9e444dc46 100644 --- a/akka-docs/rst/experimental/index.rst +++ b/akka-docs/rst/experimental/index.rst @@ -19,11 +19,11 @@ prior deprecation. .. toctree:: :maxdepth: 1 - ../scala/persistence - ../scala/persistence-schema-evolution ../dev/multi-node-testing ../java/lambda-actors ../java/lambda-fsm + ../scala/persistence-query + ../scala/typed Another reason for marking a module as experimental is that it's too early to tell if the module has a maintainer that can take the responsibility diff --git a/akka-docs/rst/java/lambda-persistence.rst b/akka-docs/rst/java/lambda-persistence.rst index 85912a5e2f..fec5eb3213 100644 --- a/akka-docs/rst/java/lambda-persistence.rst +++ b/akka-docs/rst/java/lambda-persistence.rst @@ -381,6 +381,25 @@ restarts of the persistent actor. Views ===== +.. warning:: + + ``AbstractPersistentView`` is deprecated. Use :ref:`persistence-query-java` instead. The corresponding + query type is ``EventsByPersistenceId``. There are several alternatives for connecting the ``Source`` + to an actor corresponding to a previous ``UntypedPersistentView`` actor: + + * `Sink.actorRef`_ is simple, but has the disadvantage that there is no back-pressure signal from the + destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow + * `mapAsync`_ combined with :ref:`actors-ask-lambda` is almost as simple with the advantage of back-pressure + being propagated all the way + * `ActorSubscriber`_ in case you need more fine grained control + + The consuming actor may be a plain ``AbstractActor`` or an ``AbstractPersistentActor`` if it needs to store its + own state (e.g. fromSequenceNr offset). + +.. _Sink.actorRef: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/java/stream-integrations.html#Sink_actorRef +.. _mapAsync: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/stages-overview.html#Asynchronous_processing_stages +.. _ActorSubscriber: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/java/stream-integrations.html#ActorSubscriber + Persistent 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. @@ -637,6 +656,13 @@ Persistent FSM Its internal state is persisted as a sequence of changes, later referred to as domain events. Relationship between incoming messages, FSM's states and transitions, persistence of domain events is defined by a DSL. +.. warning:: + + ``AbstractPersistentFSM`` is marked as **“experimental”** as of its introduction in Akka 2.4.0. We will continue to + improve this API based on our users’ feedback, which implies that while we try to keep incompatible + changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the + contents of the `classes related to ``AbstractPersistentFSM``. + A Simple Example ---------------- To demonstrate the features of the ``AbstractPersistentFSM``, consider an actor which represents a Web store customer. diff --git a/akka-docs/rst/java/persistence.rst b/akka-docs/rst/java/persistence.rst index f8839f5b98..2cfe0ff49a 100644 --- a/akka-docs/rst/java/persistence.rst +++ b/akka-docs/rst/java/persistence.rst @@ -384,6 +384,25 @@ restarts of the persistent actor. Persistent Views ================ +.. warning:: + + ``UntypedPersistentView`` is deprecated. Use :ref:`persistence-query-java` instead. The corresponding + query type is ``EventsByPersistenceId``. There are several alternatives for connecting the ``Source`` + to an actor corresponding to a previous ``UntypedPersistentView`` actor: + + * `Sink.actorRef`_ is simple, but has the disadvantage that there is no back-pressure signal from the + destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow + * `mapAsync`_ combined with :ref:`actors-ask-lambda` is almost as simple with the advantage of back-pressure + being propagated all the way + * `ActorSubscriber`_ in case you need more fine grained control + + The consuming actor may be a plain ``UntypedActor`` or an ``UntypedPersistentActor`` if it needs to store its + own state (e.g. fromSequenceNr offset). + +.. _Sink.actorRef: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/java/stream-integrations.html#Sink_actorRef +.. _mapAsync: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/stages-overview.html#Asynchronous_processing_stages +.. _ActorSubscriber: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/java/stream-integrations.html#ActorSubscriber + Persistent views can be implemented by extending the ``UntypedPersistentView`` trait and implementing the ``onReceive`` and the ``persistenceId`` methods. diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst index 4ba39be7fd..7caee71283 100644 --- a/akka-docs/rst/java/untyped-actors.rst +++ b/akka-docs/rst/java/untyped-actors.rst @@ -492,6 +492,8 @@ different one. Outside of an actor and if no reply is needed the second argument can be ``null``; if a reply is needed outside of an actor you can use the ask-pattern described next.. +.. _actors-ask-java: + Ask: Send-And-Receive-Future ---------------------------- diff --git a/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst b/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst index 285fbf5748..dfd467e646 100644 --- a/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst +++ b/akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst @@ -4,258 +4,5 @@ Migration Guide 2.2.x to 2.3.x ################################ -The 2.3 release contains some structural changes that require some -simple, mechanical source-level changes in client code. - -When migrating from earlier versions you should first follow the instructions for -migrating :ref:`1.3.x to 2.0.x ` and then :ref:`2.0.x to 2.1.x ` -and then :ref:`2.1.x to 2.2.x `. - -Removed hand over data in cluster singleton -=========================================== - -The support for passing data from previous singleton instance to new instance -in a graceful leaving scenario has been removed. Valuable state should be persisted -in durable storage instead, e.g. using akka-persistence. The constructor/props parameters -of ``ClusterSingletonManager`` has been changed to ordinary ``Props`` parameter for the -singleton actor instead of the factory parameter. - -Changed cluster auto-down configuration -======================================= - -``akka.cluster.auto-down`` setting has been replaced by ``akka.cluster.auto-down-unreachable-after``, -which instructs the cluster to automatically mark unreachable nodes as DOWN after this -configured time of unreachability. This feature is disabled by default, as it also was in 2.2.x. - -During the deprecation phase ``akka.cluster.auto-down=on`` is interpreted at as instant auto-down. - -Routers -======= - -The routers have been cleaned up and enhanced. The routing logic has been extracted to be usable within -normal actors as well. Some usability problems have been have been solved, such as properly reject invalid -configuration combinations. Routees can be dynamically added and removed by sending special management messages -to the router. - -The two types of routers have been named ``Pool`` and ``Group`` to make them more distinguishable and reduce confusion -of their subtle differences: - -* Pool - The router creates routees as child actors and removes them from the router if they - terminate. - -* Group - The routee actors are created externally to the router and the router sends - messages to the specified path using actor selection, without watching for termination. - -Configuration of routers is compatible with 2.2.x, but the ``router`` type should preferably be specified -with ``-pool`` or ``-group`` suffix. - -Some classes used for programmatic definition of routers have been renamed, but the old classes remain as -deprecated. The compiler will guide you with deprecation warning. For example ``RoundRobinRouter`` has -been renamed to ``RoundRobinPool`` or ``RoundRobinGroup`` depending on which type you are actually using. - -There is no replacement for ``SmallestMailboxRouter`` combined with routee paths, i.e. a group, because that -combination is not useful. - -An optional API enhancement that makes the code read better is to use the ``props`` method instead of ``withRouter``. -``withRouter`` has not been deprecated and you can continue to use that if you prefer that way of defining a router. - -Example in Scala:: - - context.actorOf(FromConfig.props(Props[Worker]), "router1") - context.actorOf(RoundRobinPool(5).props(Props[Worker]), "router2") - -Example in Java:: - - getContext().actorOf(FromConfig.getInstance().props(Props.create(Worker.class)), - "router1"); - - getContext().actorOf(new RoundRobinPool(5).props(Props.create(Worker.class)), - "router2"); - -To support multiple routee paths for a cluster aware router sending to paths the deployment configuration -property ``cluster.routees-path`` has been changed to string list ``routees.paths`` property. -The old ``cluster.routees-path`` is deprecated, but still working during the deprecation phase. - -Example:: - - /router4 { - router = round-robin-group - nr-of-instances = 10 - routees.paths = ["/user/myserviceA", "/user/myserviceB"] - cluster.enabled = on - } - -The API for creating custom routers and resizers have changed without keeping the old API as deprecated. -That should be a an API used by only a few users and they should be able to migrate to the new API -without much trouble. - -Read more about the new routers in the :ref:`documentation for Scala ` and -:ref:`documentation for Java `. - -Akka IO is no longer experimental -================================= - -The core IO layer introduced in Akka 2.2 is now a fully supported module of Akka. - -Experimental Pipelines IO abstraction has been removed -====================================================== - -Pipelines in the form introduced by 2.2 has been found unintuitive and are therefore discontinued. -A new more flexible and easier-to-use abstraction will replace their role in the future. Pipelines -will be still available in the 2.2 series. - -Changed cluster expected-response-after configuration -===================================================== - -Configuration property ``akka.cluster.failure-detector.heartbeat-request.expected-response-after`` -has been renamed to ``akka.cluster.failure-detector.expected-response-after``. - -Removed automatic retry feature from Remoting in favor of retry-gate -==================================================================== - -The retry-gate feature is now the only failure handling strategy in Remoting. This change means that when remoting detects faulty -connections it goes into a gated state where all buffered and subsequent remote messages are dropped until the configurable -time defined by the configuration key ``akka.remote.retry-gate-closed-for`` elapses after the failure event. This -behavior prevents reconnect storms and unbounded buffer growth during network instabilities. After the configured -time elapses the gate is lifted and a new connection will be attempted when there are new remote messages to be -delivered. - -In concert with this change all settings related to the old reconnect behavior (``akka.remote.retry-window`` and -``akka.remote.maximum-retries-in-window``) were removed. - -The timeout setting ``akka.remote.gate-invalid-addresses-for`` that controlled the gate interval for certain failure -events is also removed and all gating intervals are now controlled by the ``akka.remote.retry-gate-closed-for`` setting -instead. - -Reduced default sensitivity settings for transport failure detector in Remoting -=============================================================================== - -Since the most commonly used transport with Remoting is TCP, which provides proper connection termination events the failure detector sensitivity -setting ``akka.remote.transport-failure-detector.acceptable-heartbeat-pause`` now defaults to 20 seconds to reduce load induced -false-positive failure detection events in remoting. In case a non-connection-oriented protocol is used it is recommended -to change this and the ``akka.remote.transport-failure-detector.heartbeat-interval`` setting to a more sensitive value. - -Quarantine is now permanent -=========================== - -The setting that controlled the length of quarantine ``akka.remote.quarantine-systems-for`` has been removed. The only -setting available now is ``akka.remote.prune-quarantine-marker-after`` which influences how long quarantine tombstones -are kept around to avoid long-term memory leaks. This new setting defaults to 5 days. - -Remoting uses a dedicated dispatcher by default -=============================================== - -The default value of ``akka.remote.use-dispatcher`` has been changed to a dedicated dispatcher. - -Dataflow is Deprecated -====================== - -Akka dataflow is superseded by `Scala Async `_. - -Durable Mailboxes are Deprecated -================================ - -Durable mailboxes are superseded by ``akka-persistence``, which offers several -tools to support reliable messaging. - -Read more about ``akka-persistence`` in the :ref:`documentation for Scala ` and -:ref:`documentation for Java `. - -Deprecated STM Support for Agents -================================= - -Agents participating in enclosing STM transaction is a deprecated feature. - -Transactor Module is Deprecated -=============================== - -The integration between actors and STM in the module ``akka-transactor`` is deprecated and will be -removed in a future version. - -Typed Channels has been removed -=============================== - -Typed channels were an experimental feature which we decided to remove: its implementation relied -on an experimental feature of Scala for which there is no correspondence in Java and other languages and -its usage was not intuitive. - -Removed Deprecated Features -=========================== - -The following, previously deprecated, features have been removed: - - * `event-handlers renamed to loggers `_ - * `API changes to FSM and TestFSMRef `_ - * DefaultScheduler superseded by LightArrayRevolverScheduler - * all previously deprecated construction and deconstruction methods for Props - -publishCurrentClusterState is Deprecated -======================================== - -Use ``sendCurrentClusterState`` instead. Note that you can also retrieve the current cluster state -with the new ``Cluster(system).state``. - - -CurrentClusterState is not a ClusterDomainEvent -=============================================== - -``CurrentClusterState`` does not implement the ``ClusterDomainEvent`` marker interface any more. - -Note the new ``initialStateMode`` parameter of ``Cluster.subscribe``, which makes it possible -to handle the initial state as events instead of ``CurrentClusterState``. See -:ref:`documentation for Scala ` and -:ref:`documentation for Java `. - - -BalancingDispatcher is Deprecated -================================= - -Use ``BalancingPool`` instead of ``BalancingDispatcher``. See :ref:`documentation for Scala ` and -:ref:`documentation for Java `. - -During a migration period you can still use BalancingDispatcher by specifying the full class name in the dispatcher configuration:: - - type = "akka.dispatch.BalancingDispatcherConfigurator" - -akka-sbt-plugin is Removed -========================== - -``akka-sbt-plugin`` for packaging of application binaries has been removed. Version 2.2.3 can still be used -independent of Akka version of the application. Version 2.2.3 can be used with both sbt 0.12 and 0.13. - -`sbt-native-packager `_ is the recommended tool for creating -distributions of Akka applications when using sbt. - -Parens Added to sender -====================== - -Parens were added to the ``sender()`` method of the Actor Scala API to highlight that the ``sender()`` reference is not referentially transparent and must not be exposed to other threads, for example by closing over it when using future callbacks. - -It is recommended to use this new convention:: - - sender() ! "reply" - -However, it is not mandatory to use parens and you do not have to change anything. - -ReliableProxy Constructor Changed -================================= - -The constructor of ``ReliableProxy`` in ``akka-contrib`` has been changed to take an ``ActorPath`` instead of -an ``ActorRef``. Also it takes new parameters to support reconnection. Use the new props factory methods, ``ReliableProxy.props``. - -Akka OSGi Aries Blueprint is Removed -==================================== - -``akka-osgi-aries`` has been removed. Similar can be implemented outside of Akka if needed. - -TestKit: reworked time dilation -=============================== - -``TestDuration`` has been changed into an implicit value class plus a Java API in JavaTestKit. Please change:: - - import akka.testkit.duration2TestDuration - -into:: - - import akka.testkit.TestDuration - +Migration from 2.2.x to 2.3.x is described in the +`documentation of 2.3 `_. \ No newline at end of file diff --git a/akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst b/akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst index 5c088e7b55..f961fb3ff8 100644 --- a/akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst +++ b/akka-docs/rst/project/migration-guide-2.3.x-2.4.x.rst @@ -30,6 +30,46 @@ in practice. No changes were needed to the Akka source code for this update. Use depend on 3.8.0.Final that break with 3.10.3.Final should be able to manually downgrade the dependency to 3.8.0.Final and Akka will still work with that version. +Advanced Notice: TypedActors will go away +========================================= + +While technically not yet deprecated, the current ``akka.actor.TypedActor`` support will be superseded by +the :ref:`typed-scala` project that is currently being developed in open preview mode. If you are using TypedActors +in your projects you are advised to look into this, as it is superior to the Active Object pattern expressed +in TypedActors. The generic ActorRefs in Akka Typed allow the same type-safety that is afforded by +TypedActors while retaining all the other benefits of an explicit actor model (including the ability to +change behaviors etc.). + +It is likely that TypedActors will be officially deprecated in the next major update of Akka and subsequently removed. + +Removed Deprecated Features +=========================== + +The following, previously deprecated, features have been removed: + +* akka-dataflow + +* akka-transactor + +* durable mailboxes (akka-mailboxes-common, akka-file-mailbox) + +* Cluster.publishCurrentClusterState + +* akka.cluster.auto-down, replaced by akka.cluster.auto-down-unreachable-after in Akka 2.3 + +* Old routers and configuration. + + Note that in router configuration you must now specify if it is a ``pool`` or a ``group`` + in the way that was introduced in Akka 2.3. + +* Timeout constructor without unit + +* JavaLoggingEventHandler, replaced by JavaLogger + +* UntypedActorFactory + +* Java API TestKit.dilated, moved to JavaTestKit.dilated + Added parameter validation to RootActorPath =========================================== Previously ``akka.actor.RootActorPath`` allowed passing in arbitrary strings into its name parameter, @@ -40,18 +80,6 @@ such as using ``actorSelection`` on such invalid path. In Akka 2.4.x the ``RootActorPath`` validates the input and may throw an ``IllegalArgumentException`` if the passed in name string is illegal (contains ``/`` elsewhere than in the begining of the string or contains ``#``). -Advanced Notice: TypedActors will go away -========================================= - -While technically not yet deprecated, the current ``akka.actor.TypedActor`` support will be superseded by -the Akka Typed project that is currently being developed in open preview mode. If you are using TypedActors -in your projects you are advised to look into this, as it is superior to the Active Object pattern expressed -in TypedActors. The generic ActorRefs in Akka Typed allow the same type-safety that is afforded by -TypedActors while retaining all the other benefits of an explicit actor model (including the ability to -change behaviors etc.). - -It is likely that TypedActors will be officially deprecated in the next major update of Akka and subsequently removed. - TestKit.remaining throws AssertionError ======================================= @@ -93,14 +121,6 @@ Which turns out to be useful in many systems where same-state transitions actual In case you do *not* want to trigger a state transition event when effectively performing an ``X->X`` transition, use ``stay()`` instead. -Cluster Sharding Entry Path Change -================================== -Previously in ``2.3.x`` entries were direct children of the local ``ShardRegion``. In examples the ``persistenceId`` of entries -included ``self.path.parent.name`` to include the cluster type name. - -In ``2.4.x`` entries are now children of a ``Shard``, which in turn is a child of the local ``ShardRegion``. To include the shard -type in the ``persistenceId`` it is now accessed by ``self.path.parent.parent.name`` from each entry. - Circuit Breaker Timeout Change ============================== @@ -109,34 +129,6 @@ In ``2.3.x`` calls protected by the ``CircuitBreaker`` were allowed to run indef In ``2.4.x`` the failureCount of the Breaker will be increased as soon as the timeout is reached and a ``Failure[TimeoutException]`` will be returned immediately for asynchronous calls. Synchronous calls will now throw a ``TimeoutException`` after the call is finished. -Removed Deprecated Features -=========================== - -The following, previously deprecated, features have been removed: - -* akka-dataflow - -* akka-transactor - -* durable mailboxes (akka-mailboxes-common, akka-file-mailbox) - -* Cluster.publishCurrentClusterState - -* akka.cluster.auto-down, replaced by akka.cluster.auto-down-unreachable-after in Akka 2.3 - -* Old routers and configuration. - - Note that in router configuration you must now specify if it is a ``pool`` or a ``group`` - in the way that was introduced in Akka 2.3. - -* Timeout constructor without unit - -* JavaLoggingEventHandler, replaced by JavaLogger - -* UntypedActorFactory - -* Java API TestKit.dilated, moved to JavaTestKit.dilated - Slf4j logging filter ==================== @@ -175,6 +167,14 @@ Secure Cookies `Secure cookies` feature was deprecated. +Microkernel is Deprecated +========================= + +Akka Microkernel is deprecated and will be removed. It is replaced by using an ordinary +user defined main class and packaging with `sbt-native-packager `_ +or `Typesafe ConductR `_. +Please see :ref:`deployment-scenarios` for more information. + New Cluster Metrics Extension ============================= Previously, cluster metrics functionality was located in the ``akka-cluster`` jar. @@ -190,14 +190,6 @@ Router configuration entries have also changed for the module, they use prefix ` Metrics extension classes and objects are located in the new package ``akka.cluster.metrics``. Please see :ref:`Scala `, :ref:`Java ` for more information. -Microkernel is Deprecated -========================= - -Akka Microkernel is deprecated and will be removed. It is replaced by using an ordinary -user defined main class and packaging with `sbt-native-packager `_ -or `Typesafe ConductR `_. -Please see :ref:`deployment-scenarios` for more information. - Cluster tools moved to separate module ====================================== @@ -237,6 +229,24 @@ and the ``EntityId`` type in the Scala API. ``idExtractor`` function was renamed to ``extractEntityId``. ``shardResolver`` function was renamed to ``extractShardId``. +Cluster Sharding Entry Path Change +================================== +Previously in ``2.3.x`` entries were direct children of the local ``ShardRegion``. In examples the ``persistenceId`` of entries +included ``self.path.parent.name`` to include the cluster type name. + +In ``2.4.x`` entries are now children of a ``Shard``, which in turn is a child of the local ``ShardRegion``. To include the shard +type in the ``persistenceId`` it is now accessed by ``self.path.parent.parent.name`` from each entry. + +Asynchronous ShardAllocationStrategy +==================================== + +The methods of the ``ShardAllocationStrategy`` and ``AbstractShardAllocationStrategy`` in Cluster Sharding +have changed return type to a ``Future`` to support asynchronous decision. For example you can ask an +actor external actor of how to allocate shards or rebalance shards. + +For the synchronous case you can return the result via ``scala.concurrent.Future.successful`` in Scala or +``akka.dispatch.Futures.successful`` in Java. + ClusterSingletonManager and ClusterSingletonProxy construction ============================================================== @@ -287,16 +297,6 @@ is now started as a ``system`` actor instead of a ``user`` actor, i.e. the defau the ``ClusterClient`` initial contacts has changed to ``"akka.tcp://system@hostname:port/system/receptionist"``. -Asynchronous ShardAllocationStrategy -==================================== - -The methods of the ``ShardAllocationStrategy`` and ``AbstractShardAllocationStrategy`` in Cluster Sharding -have changed return type to a ``Future`` to support asynchronous decision. For example you can ask an -actor external actor of how to allocate shards or rebalance shards. - -For the synchronous case you can return the result via ``scala.concurrent.Future.successful`` in Scala or -``akka.dispatch.Futures.successful`` in Java. - Akka Persistence ================ @@ -392,6 +392,26 @@ max-message-batch-size config Configuration property ``akka.persistence.journal.max-message-batch-size`` has been moved into the plugin configuration section, to allow different values for different journal plugins. See ``reference.conf``. +PersistentView is deprecated +---------------------------- + +``PersistentView`` is deprecated. Use :ref:`persistence-query-scala` instead. The corresponding +query type is ``EventsByPersistenceId``. There are several alternatives for connecting the ``Source`` +to an actor corresponding to a previous ``PersistentView`` actor: + +* `Sink.actorRef`_ is simple, but has the disadvantage that there is no back-pressure signal from the + destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow +* `mapAsync`_ combined with :ref:`actors-ask-lambda` is almost as simple with the advantage of back-pressure + being propagated all the way +* `ActorSubscriber`_ in case you need more fine grained control + +The consuming actor may be a plain ``Actor`` or a ``PersistentActor`` if it needs to store its +own state (e.g. fromSequenceNr offset). + +.. _Sink.actorRef: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/scala/stream-integrations.html#Sink_actorRef +.. _mapAsync: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/stages-overview.html#Asynchronous_processing_stages +.. _ActorSubscriber: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/scala/stream-integrations.html#ActorSubscriber + Persistence Plugin APIs ======================= diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst index 99e00c08e9..ebe4e17b82 100644 --- a/akka-docs/rst/scala/actors.rst +++ b/akka-docs/rst/scala/actors.rst @@ -532,6 +532,8 @@ to reply to the original sender, by using ``sender() ! replyMsg``. If invoked from an instance that is **not** an Actor the sender will be :obj:`deadLetters` actor reference by default. +.. _actors-ask-scala: + Ask: Send-And-Receive-Future ---------------------------- diff --git a/akka-docs/rst/scala/persistence.rst b/akka-docs/rst/scala/persistence.rst index 081a7b7867..c09dbc600f 100644 --- a/akka-docs/rst/scala/persistence.rst +++ b/akka-docs/rst/scala/persistence.rst @@ -372,6 +372,25 @@ restarts of the persistent actor. Persistent Views ================ +.. warning:: + + ``PersistentView`` is deprecated. Use :ref:`persistence-query-scala` instead. The corresponding + query type is ``EventsByPersistenceId``. There are several alternatives for connecting the ``Source`` + to an actor corresponding to a previous ``PersistentView`` actor: + + * `Sink.actorRef`_ is simple, but has the disadvantage that there is no back-pressure signal from the + destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow + * `mapAsync`_ combined with :ref:`actors-ask-lambda` is almost as simple with the advantage of back-pressure + being propagated all the way + * `ActorSubscriber`_ in case you need more fine grained control + + The consuming actor may be a plain ``Actor`` or a ``PersistentActor`` if it needs to store its + own state (e.g. fromSequenceNr offset). + +.. _Sink.actorRef: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/scala/stream-integrations.html#Sink_actorRef +.. _mapAsync: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/stages-overview.html#Asynchronous_processing_stages +.. _ActorSubscriber: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/scala/stream-integrations.html#ActorSubscriber + Persistent views can be implemented by extending the ``PersistentView`` trait and implementing the ``receive`` and the ``persistenceId`` methods. @@ -643,6 +662,13 @@ Persistent FSM Its internal state is persisted as a sequence of changes, later referred to as domain events. Relationship between incoming messages, FSM's states and transitions, persistence of domain events is defined by a DSL. +.. warning:: + + ``PersistentFSM`` is marked as **“experimental”** as of its introduction in Akka 2.4.0. We will continue to + improve this API based on our users’ feedback, which implies that while we try to keep incompatible + changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the + contents of the `classes related to ``PersistentFSM``. + A Simple Example ---------------- To demonstrate the features of the ``PersistentFSM`` trait, consider an actor which represents a Web store customer. diff --git a/akka-persistence/src/main/scala/akka/persistence/PersistentView.scala b/akka-persistence/src/main/scala/akka/persistence/PersistentView.scala index 31dc835327..b0d48ea3b2 100644 --- a/akka-persistence/src/main/scala/akka/persistence/PersistentView.scala +++ b/akka-persistence/src/main/scala/akka/persistence/PersistentView.scala @@ -79,7 +79,9 @@ private[akka] object PersistentView { * * - [[autoUpdate]] for turning automated updates on or off * - [[autoUpdateReplayMax]] for limiting the number of replayed messages per view update cycle + * */ +@deprecated("use Persistence Query instead", "2.4") trait PersistentView extends Actor with Snapshotter with Stash with StashFactory with PersistenceIdentity with PersistenceRecovery with ActorLogging { @@ -383,6 +385,7 @@ trait PersistentView extends Actor with Snapshotter with Stash with StashFactory * * @see [[PersistentView]] */ +@deprecated("use Persistence Query instead", "2.4") abstract class UntypedPersistentView extends UntypedActor with PersistentView /** @@ -390,4 +393,5 @@ abstract class UntypedPersistentView extends UntypedActor with PersistentView * * @see [[PersistentView]] */ +@deprecated("use Persistence Query instead", "2.4") abstract class AbstractPersistentView extends AbstractActor with PersistentView diff --git a/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSM.scala b/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSM.scala index 8edb1935c9..5c3fa7d747 100644 --- a/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSM.scala +++ b/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSM.scala @@ -24,6 +24,8 @@ import scala.reflect.ClassTag * Persistence execution order is: persist -> wait for ack -> apply state. * Incoming messages are deferred until the state is applied. * State Data is constructed based on domain events, according to user's implementation of applyEvent function. + * + * This is an EXPERIMENTAL feature and is subject to change until it has received more real world testing. */ trait PersistentFSM[S <: FSMState, D, E] extends PersistentActor with PersistentFSMBase[S, D, E] with ActorLogging { import akka.persistence.fsm.PersistentFSM._ diff --git a/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSMBase.scala b/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSMBase.scala index d178fa2644..2bb7df4b04 100644 --- a/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSMBase.scala +++ b/akka-persistence/src/main/scala/akka/persistence/fsm/PersistentFSMBase.scala @@ -89,6 +89,8 @@ import scala.concurrent.duration.FiniteDuration * cancelTimer("tock") * isTimerActive("tock") * + * + * This is an EXPERIMENTAL feature and is subject to change until it has received more real world testing. */ trait PersistentFSMBase[S, D, E] extends Actor with Listeners with ActorLogging { @@ -534,7 +536,7 @@ trait PersistentFSMBase[S, D, E] extends Actor with Listeners with ActorLogging * Stackable trait for [[akka.actor.FSM]] which adds a rolling event log and * debug logging capabilities (analogous to [[akka.event.LoggingReceive]]). * - * @since 1.2 + * This is an EXPERIMENTAL feature and is subject to change until it has received more real world testing. */ trait LoggingPersistentFSM[S, D, E] extends PersistentFSMBase[S, D, E] { this: Actor ⇒