From db95b7ff96a94e8c07d2e64b30a7b459ae51bfe6 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Tue, 13 Dec 2016 10:54:41 +0100 Subject: [PATCH] add http api for cluster management, #21172 * reference akka/akka-cluster-management in cluster docs * deprecate the command line tool, including migration note * cleanup old migration guides * remove YourKit as sponsor, since we pay license --- akka-docs/rst/java/cluster-usage.rst | 37 +- .../project/migration-guide-2.3.x-2.4.x.rst | 680 +----------------- .../project/migration-guide-2.4.x-2.5.x.rst | 22 +- .../migration-guide-eventsourced-2.3.x.rst | 186 +---- ...e-persistence-experimental-2.3.x-2.4.x.rst | 201 +----- akka-docs/rst/project/sponsors.rst | 10 - akka-docs/rst/scala/cluster-usage.rst | 37 +- akka-kernel/src/main/dist/bin/akka-cluster | 2 + 8 files changed, 75 insertions(+), 1100 deletions(-) diff --git a/akka-docs/rst/java/cluster-usage.rst b/akka-docs/rst/java/cluster-usage.rst index ff7b2c21a4..ec0bb057ab 100644 --- a/akka-docs/rst/java/cluster-usage.rst +++ b/akka-docs/rst/java/cluster-usage.rst @@ -91,7 +91,7 @@ seed nodes in the existing cluster. If you don't configure seed nodes you need to join the cluster programmatically or manually. -Manual joining can be performed by using ref:`cluster_jmx_java` or :ref:`cluster_command_line_java`. +Manual joining can be performed by using ref:`cluster_jmx_java` or :ref:`cluster_http_java`. Joining programmatically can be performed with ``Cluster.get(system).join``. Unsuccessful join attempts are automatically retried after the time period defined in configuration property ``retry-unsuccessful-join-after``. Retries can be disabled by setting the property to ``off``. @@ -134,7 +134,7 @@ leader is not allowed to perform its duties, such as changing status of new joining members to 'Up'. The node must first become reachable again, or the status of the unreachable member must be changed to 'Down'. Changing status to 'Down' can be performed automatically or manually. By default it must be done manually, using -:ref:`cluster_jmx_java` or :ref:`cluster_command_line_java`. +:ref:`cluster_jmx_java` or :ref:`cluster_http_java`. It can also be performed programmatically with ``Cluster.get(system).down(address)``. @@ -180,7 +180,7 @@ as unreachable and removed after the automatic or manual downing as described above. A more graceful exit can be performed if you tell the cluster that a node shall leave. -This can be performed using :ref:`cluster_jmx_java` or :ref:`cluster_command_line_java`. +This can be performed using :ref:`cluster_jmx_java` or :ref:`cluster_http_java`. It can also be performed programmatically with: .. includecode:: code/docs/cluster/ClusterDocTest.java#leave @@ -637,10 +637,21 @@ The member nodes of the cluster can collect system health metrics and publish th and to the registered subscribers on the system event bus with the help of :doc:`cluster-metrics`. +Management +^^^^^^^^^^ + +.. _cluster_http_java: + +HTTP +---- + +Information and management of the cluster is available with a HTTP API. +See documentation of `akka/akka-cluster-management `_. + .. _cluster_jmx_java: JMX -^^^ +--- Information and management of the cluster is available as JMX MBeans with the root name ``akka.Cluster``. The JMX information can be displayed with an ordinary JMX console such as JConsole or JVisualVM. @@ -658,8 +669,13 @@ Member nodes are identified by their address, in format `akka.://`_ + or similar instead. The cluster can be managed with the script `bin/akka-cluster` provided in the Akka distribution. @@ -690,13 +706,8 @@ Run it without parameters to see instructions about how to use the script:: To be able to use the script you must enable remote monitoring and management when starting the JVMs of the cluster nodes, -as described in `Monitoring and Management Using JMX Technology `_ - -Example of system properties to enable remote monitoring and management:: - - java -Dcom.sun.management.jmxremote.port=9999 \ - -Dcom.sun.management.jmxremote.authenticate=false \ - -Dcom.sun.management.jmxremote.ssl=false +as described in `Monitoring and Management Using JMX Technology `_. +Make sure you understand the security implications of enabling remote monitoring and management. .. _cluster_configuration_java: 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 c19b5a6854..e5fb497cf9 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 @@ -4,681 +4,5 @@ Migration Guide 2.3.x to 2.4.x ############################## -The 2.4 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 ` and then :ref:`2.2.x to 2.3.x `. - -Binary Compatibility -==================== - -Akka 2.4.x is backwards binary compatible with previous 2.3.x versions apart from the following -exceptions. This means that the new JARs are a drop-in replacement for the old one -(but not the other way around) as long as your build does not enable the inliner (Scala-only restriction). - -The following parts are not binary compatible with 2.3.x: - -* akka-testkit and akka-remote-testkit -* experimental modules, such as akka-persistence and akka-contrib -* features, classes, methods that were deprecated in 2.3.x and removed in 2.4.x - -The dependency to **Netty** has been updated from version 3.8.0.Final to 3.10.3.Final. The changes in -those versions might not be fully binary compatible, but we believe that it will not be a problem -in practice. No changes were needed to the Akka source code for this update. Users of libraries that -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 - -Protobuf Dependency -=================== - -The transitive dependency to Protobuf has been removed to make it possible to use any version -of Protobuf for the application messages. If you use Protobuf in your application you need -to add the following dependency with desired version number:: - - "com.google.protobuf" % "protobuf-java" % "2.5.0" - -Internally Akka is using an embedded version of protobuf that corresponds to ``com.google.protobuf/protobuf-java`` -version 2.5.0. The package name of the embedded classes has been changed to ``akka.protobuf``. - -Added parameter validation to RootActorPath -=========================================== -Previously ``akka.actor.RootActorPath`` allowed passing in arbitrary strings into its name parameter, -which is meant to be the *name* of the root Actor. Subsequently, if constructed with an invalid name -such as a full path for example (``/user/Full/Path``) some features using this path may transparently fail - -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 ``#``). - -TestKit.remaining throws AssertionError -======================================= - -In earlier versions of Akka `TestKit.remaining` returned the default timeout configurable under -"akka.test.single-expect-default". This was a bit confusing and thus it has been changed to throw an -AssertionError if called outside of within. The old behavior however can still be achieved by -calling `TestKit.remainingOrDefault` instead. - -EventStream and ManagedActorClassification EventBus now require an ActorSystem -============================================================================== - -Both the ``EventStream`` (:ref:`Scala `, :ref:`Java `) and the -``ManagedActorClassification``, ``ManagedActorEventBus`` (:ref:`Scala `, :ref:`Java `) now -require an ``ActorSystem`` to properly operate. The reason for that is moving away from stateful internal lifecycle checks -to a fully reactive model for unsubscribing actors that have ``Terminated``. Therefore the ``ActorClassification`` -and ``ActorEventBus`` was deprecated and replaced by ``ManagedActorClassification`` and ``ManagedActorEventBus`` - -If you have implemented a custom event bus, you will need to pass in the actor system through the constructor now: - -.. includecode:: ../scala/code/docs/event/EventBusDocSpec.scala#actor-bus - -If you have been creating EventStreams manually, you now have to provide an actor system and *start the unsubscriber*: - -.. includecode:: ../../../akka-actor-tests/src/test/scala/akka/event/EventStreamSpec.scala#event-bus-start-unsubscriber-scala - -Please note that this change affects you only if you have implemented your own buses, Akka's own ``context.eventStream`` -is still there and does not require any attention from you concerning this change. - -FSM notifies on same state transitions -====================================== -When changing states in an Finite-State-Machine Actor (``FSM``), state transition events are emitted and can be handled by the user -either by registering ``onTransition`` handlers or by subscribing to these events by sending it an ``SubscribeTransitionCallBack`` message. - -Previously in ``2.3.x`` when an ``FSM`` was in state ``A`` and performed a ``goto(A)`` transition, no state transition notification would be sent. -This is because it would effectively stay in the same state, and was deemed to be semantically equivalent to calling ``stay()``. - -In ``2.4.x`` when an ``FSM`` performs an any ``goto(X)`` transition, it will always trigger state transition events. -Which turns out to be useful in many systems where same-state transitions actually should have an effect. - -In case you do *not* want to trigger a state transition event when effectively performing an ``X->X`` transition, use ``stay()`` instead. - - -Circuit Breaker Timeout Change -============================== -In ``2.3.x`` calls protected by the ``CircuitBreaker`` were allowed to run indefinitely and the check to see if the timeout had been exceeded was done after the call had returned. - -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. - - -Slf4j logging filter -==================== - -If you use ``Slf4jLogger`` you should add the following configuration:: - - akka.logging-filter = "akka.event.slf4j.Slf4jLoggingFilter" - -It will filter the log events using the backend configuration (e.g. logback.xml) before -they are published to the event bus. - -Inbox.receive Java API -====================== - -``Inbox.receive`` now throws a checked ``java.util.concurrent.TimeoutException`` exception if the receive timeout -is reached. - - -Pool routers nrOfInstances method now takes ActorSystem -======================================================= - -In order to make cluster routers smarter about when they can start local routees, -``nrOfInstances`` defined on ``Pool`` now takes ``ActorSystem`` as an argument. -In case you have implemented a custom Pool you will have to update the method's signature, -however the implementation can remain the same if you don't need to rely on an ActorSystem in your logic. - -Group routers paths method now takes ActorSystem -================================================ - -In order to make cluster routers smarter about when they can start local routees, -``paths`` defined on ``Group`` now takes ``ActorSystem`` as an argument. -In case you have implemented a custom Group you will have to update the method's signature, -however the implementation can remain the same if you don't need to rely on an ActorSystem in your logic. - -Cluster aware router max-total-nr-of-instances -============================================== - -In 2.3.x the deployment configuration property ``nr-of-instances`` was used for -cluster aware routers to specify total number of routees in the cluster. -This was confusing, especially since the default value is 1. - -In 2.4.x there is a new deployement property ``cluster.max-total-nr-of-instances`` that -defines total number of routees in the cluster. By default ``max-total-nr-of-instances`` -is set to a high value (10000) that will result in new routees added to the router when nodes join the cluster. -Set it to a lower value if you want to limit total number of routees. - -For backwards compatibility reasons ``nr-of-instances`` is still used if defined by user, -i.e. if defined it takes precedence over ``max-total-nr-of-instances``. - -Logger names use full class name -================================ -Previously, few places in Akka used "simple" logger names, such as ``Cluster`` or ``Remoting``. -Now they use full class names, such as ``akka.cluster.Cluster`` or ``akka.remote.Remoting``, -in order to allow package level log level definitions and ease source code lookup. -In case you used specific "simple" logger name based rules in your ``logback.xml`` configurations, -please change them to reflect appropriate package name, such as -```` or ```` - -Default interval for TestKit.awaitAssert changed to 100 ms -========================================================== - -Default check interval changed from 800 ms to 100 ms. You can define the interval explicitly if you need a -longer interval. - -Secure Cookies -============== - -`Secure cookies` feature was deprecated. - -AES128CounterInetRNG and AES256CounterInetRNG are Deprecated -============================================================ - -Use ``AES128CounterSecureRNG`` or ``AES256CounterSecureRNG`` as -``akka.remote.netty.ssl.security.random-number-generator``. - -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 `Lightbend ConductR `_. -Please see :ref:`deployment-scenarios` for more information. - -New Cluster Metrics Extension -============================= -Previously, cluster metrics functionality was located in the ``akka-cluster`` jar. -Now it is split out and moved into a separate Akka module: ``akka-cluster-metrics`` jar. -The module comes with few enhancements, such as use of Kamon sigar-loader -for native library provisioning as well as use of statistical averaging of metrics data. -Note that both old and new metrics configuration entries in the ``reference.conf`` -are still in the same name space ``akka.cluster.metrics`` but are not compatible. -Make sure to disable legacy metrics in akka-cluster: ``akka.cluster.metrics.enabled=off``, -since it is still enabled in akka-cluster by default (for compatibility with past releases). -Router configuration entries have also changed for the module, they use prefix ``cluster-metrics-``: -``cluster-metrics-adaptive-pool`` and ``cluster-metrics-adaptive-group`` -Metrics extension classes and objects are located in the new package ``akka.cluster.metrics``. -Please see :ref:`Scala `, :ref:`Java ` for more information. - -Cluster tools moved to separate module -====================================== - -The Cluster Singleton, Distributed Pub-Sub, and Cluster Client previously located in the ``akka-contrib`` -jar is now moved to a separate module named ``akka-cluster-tools``. You need to replace this dependency -if you use any of these tools. - -The classes changed package name from ``akka.contrib.pattern`` to ``akka.cluster.singleton``, ``akka.cluster.pubsub`` -and ``akka.cluster.client``. - -The configuration properties changed name to ``akka.cluster.pub-sub`` and ``akka.cluster.client``. - -Cluster sharding moved to separate module -========================================= - -The Cluster Sharding previously located in the ``akka-contrib`` jar is now moved to a separate module -named ``akka-cluster-sharding``. You need to replace this dependency if you use Cluster Sharding. - -The classes changed package name from ``akka.contrib.pattern`` to ``akka.cluster.sharding``. - -The configuration properties changed name to ``akka.cluster.sharding``. - -ClusterSharding construction -============================ - -Several parameters of the ``start`` method of the ``ClusterSharding`` extension are now defined -in a settings object ``ClusterShardingSettings``. -It can be created from system configuration properties and also amended with API. -These settings can be defined differently per entry type if needed. - -Starting the ``ShardRegion`` in proxy mode is now done with the ``startProxy`` method -of the ``ClusterSharding`` extension instead of the optional ``entryProps`` parameter. - -Entry was renamed to Entity, for example in the ``MessagesExtractor`` in the Java API -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. - -Cluster Sharding internal data -============================== - -The Cluster Sharding coordinator stores the locations of the shards using Akka Persistence. -This data can safely be removed when restarting the whole Akka Cluster. - -The serialization format of the internal persistent events stored by the Cluster Sharding coordinator -has been changed and it cannot load old data from 2.3.x or some 2.4 milestone. - -The ``persistenceId`` of the Cluster Sharding coordinator has been changed since 2.3.x so -it should not load such old data, but it can be a problem if you have used a 2.4 -milestone release. In that case you should remove the persistent data that the -Cluster Sharding coordinator stored. Note that this is not application data. - -You can use the :ref:`RemoveInternalClusterShardingData ` -utility program to remove this data. - -The new ``persistenceId`` is ``s"/sharding/${typeName}Coordinator"``. -The old ``persistenceId`` is ``s"/user/sharding/${typeName}Coordinator/singleton/coordinator"``. - -ClusterSingletonManager and ClusterSingletonProxy construction -============================================================== - -Parameters to the ``Props`` factory methods have been moved to settings object ``ClusterSingletonManagerSettings`` -and ``ClusterSingletonProxySettings``. These can be created from system configuration properties and also -amended with API as needed. - -The buffer size of the ``ClusterSingletonProxy`` can be defined in the ``ClusterSingletonProxySettings`` -instead of defining ``stash-capacity`` of the mailbox. Buffering can be disabled by using a -buffer size of 0. - -The ``singletonPath`` parameter of ``ClusterSingletonProxy.props`` has changed. It is now named -``singletonManagerPath`` and is the logical path of the singleton manager, e.g. ``/user/singletonManager``, -which ends with the name you defined in ``actorOf`` when creating the ``ClusterSingletonManager``. -In 2.3.x it was the path to singleton instance, which was error-prone because one had to provide both -the name of the singleton manager and the singleton actor. - -DistributedPubSub construction -============================== - -Normally, the ``DistributedPubSubMediator`` actor is started by the ``DistributedPubSubExtension``. -This extension has been renamed to ``DistributedPubSub``. It is also possible to start -it as an ordinary actor if you need multiple instances of it with different settings. -The parameters of the ``Props`` factory methods in the ``DistributedPubSubMediator`` companion -has been moved to settings object ``DistributedPubSubSettings``. This can be created from -system configuration properties and also amended with API as needed. - -ClusterClient construction -========================== - -The parameters of the ``Props`` factory methods in the ``ClusterClient`` companion -has been moved to settings object ``ClusterClientSettings``. This can be created from -system configuration properties and also amended with API as needed. - -The buffer size of the ``ClusterClient`` can be defined in the ``ClusterClientSettings`` -instead of defining ``stash-capacity`` of the mailbox. Buffering can be disabled by using a -buffer size of 0. - -Normally, the ``ClusterReceptionist`` actor is started by the ``ClusterReceptionistExtension``. -This extension has been renamed to ``ClusterClientReceptionist``. It is also possible to start -it as an ordinary actor if you need multiple instances of it with different settings. -The parameters of the ``Props`` factory methods in the ``ClusterReceptionist`` companion -has been moved to settings object ``ClusterReceptionistSettings``. This can be created from -system configuration properties and also amended with API as needed. - -The ``ClusterReceptionist`` actor that is started by the ``ClusterReceptionistExtension`` -is now started as a ``system`` actor instead of a ``user`` actor, i.e. the default path for -the ``ClusterClient`` initial contacts has changed to -``"akka.tcp://system@hostname:port/system/receptionist"``. - -ClusterClient sender -==================== - -In 2.3 the ``sender()`` of the response messages, as seen by the client, was the -actor in cluster. - -In 2.4 the ``sender()`` of the response messages, as seen by the client, is ``deadLetters`` -since the client should normally send subsequent messages via the ``ClusterClient``. -It is possible to pass the original sender inside the reply messages if -the client is supposed to communicate directly to the actor in the cluster. - -Akka Persistence -================ - -Experimental removed --------------------- - -The artifact name has changed from ``akka-persistence-experimental`` to ``akka-persistence``. - -New sbt dependency:: - - "com.typesafe.akka" %% "akka-persistence" % "@version@" @crossString@ - -New Maven dependency:: - - - com.typesafe.akka - akka-persistence_@binVersion@ - @version@ - - -The artefact name of the Persistent TCK has changed from ``akka-persistence-tck-experimental`` (``akka-persistence-experimental-tck``) to -``akka-persistence-tck``. - -Mandatory persistenceId ------------------------ - -It is now mandatory to define the ``persistenceId`` in subclasses of ``PersistentActor``, ``UntypedPersistentActor`` -and ``AbstractPersistentId``. - -The rationale behind this change being stricter de-coupling of your Actor hierarchy and the logical -"which persistent entity this actor represents". - -In case you want to preserve the old behavior of providing the actor's path as the default ``persistenceId``, you can easily -implement it yourself either as a helper trait or simply by overriding ``persistenceId`` as follows:: - - override def persistenceId = self.path.toStringWithoutAddress - -Failures --------- - -Backend journal failures during recovery and persist are treated differently than in 2.3.x. The ``PersistenceFailure`` -message is removed and the actor is unconditionally stopped. The new behavior and reasons for it is explained in -:ref:`failures-scala`. - -Persist sequence of events --------------------------- - -The ``persist`` method that takes a ``Seq`` (Scala) or ``Iterable`` (Java) of events parameter was deprecated and -renamed to ``persistAll`` to avoid mistakes of persisting other collection types as one single event by calling -the overloaded ``persist(event)`` method. - -non-permanent deletion ----------------------- - -The ``permanent`` flag in ``deleteMessages`` was removed. non-permanent deletes are not supported -any more. Events that were deleted with ``permanent=false`` with older version will -still not be replayed in this version. - -Recover message is gone, replaced by Recovery config ----------------------------------------------------- -Previously the way to cause recover in PersistentActors was sending them a ``Recover()`` message. -Most of the time it was the actor itself sending such message to ``self`` in its ``preStart`` method, -however it was possible to send this message from an external source to any ``PersistentActor`` or ``PresistentView`` -to make it start recovering. - -This style of starting recovery does not fit well with usual Actor best practices: an Actor should be independent -and know about its internal state, and also about its recovery or lack thereof. In order to guide users towards -more independent Actors, the ``Recovery()`` object is now not used as a message, but as configuration option -used by the Actor when it starts. In order to migrate previous code which customised its recovery mode use this example -as reference:: - - // previously - class OldCookieMonster extends PersistentActor { - def preStart() = self ! Recover(toSequenceNr = 42L) - // ... - } - // now: - class NewCookieMonster extends PersistentActor { - override def recovery = Recovery(toSequenceNr = 42L) - // ... - } - -Sender reference of replayed events is deadLetters --------------------------------------------------- -While undocumented, previously the ``sender()`` of the replayed messages would be the same sender that originally had -sent the message. Since sender is an ``ActorRef`` and those events are often replayed in different incarnations of -actor systems and during the entire lifetime of the app, relying on the existence of this reference is most likely -not going to succeed. In order to avoid bugs in the style of "it worked last week", the ``sender()`` reference is now not -stored, in order to avoid potential bugs which this could have provoked. - -The previous behaviour was never documented explicitly (nor was it a design goal), so it is unlikely that applications -have explicitly relied on this behaviour, however if you find yourself with an application that did exploit this you -should rewrite it to explicitly store the ``ActorPath`` of where such replies during replay may have to be sent to, -instead of relying on the sender reference during replay. - -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``. - -akka.persistence.snapshot-store.plugin config ---------------------------------------------- - -The configuration property ``akka.persistence.snapshot-store.plugin`` now by default is empty. To restore the previous -setting add ``akka.persistence.snapshot-store.plugin = "akka.persistence.snapshot-store.local"`` to your application.conf. -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 -======================= - -SyncWriteJournal removed ------------------------- - -``SyncWriteJournal`` removed in favor of using ``AsyncWriteJournal``. - -If the storage backend API only supports synchronous, blocking writes, -the methods can still be implemented in terms of the asynchronous API. -Example of how to do that is in included in the -See :ref:`Journal plugin API for Scala ` -or :ref:`Journal plugin API for Java `. - -SnapshotStore: Snapshots can now be deleted asynchronously (and report failures) --------------------------------------------------------------------------------- -Previously the ``SnapshotStore`` plugin SPI did not allow for asynchronous deletion of snapshots, -and failures of deleting a snapshot may have been even silently ignored. - -Now ``SnapshotStore`` must return a ``Future`` representing the deletion of the snapshot. -If this future completes successfully the ``PersistentActor`` which initiated the snapshotting will -be notified via an ``DeleteSnapshotSuccess`` message. If the deletion fails for some reason a ``DeleteSnapshotFailure`` -will be sent to the actor instead. - -For ``criteria`` based deletion of snapshots (``def deleteSnapshots(criteria: SnapshotSelectionCriteria)``) equivalent -``DeleteSnapshotsSuccess`` and ``DeleteSnapshotsFailure`` messages are sent, which contain the specified criteria, -instead of ``SnapshotMetadata`` as is the case with the single snapshot deletion messages. - -SnapshotStore: Removed 'saved' callback ---------------------------------------- -Snapshot Stores previously were required to implement a ``def saved(meta: SnapshotMetadata): Unit`` method which -would be called upon successful completion of a ``saveAsync`` (``doSaveAsync`` in Java API) snapshot write. - -Currently all journals and snapshot stores perform asynchronous writes and deletes, thus all could potentially benefit -from such callback methods. The only gain these callback give over composing an ``onComplete`` over ``Future`` returned -by the journal or snapshot store is that it is executed in the Actors context, thus it can safely (without additional -synchronization modify its internal state - for example a "pending writes" counter). - -However, this feature was not used by many plugins, and expanding the API to accomodate all callbacks would have grown -the API a lot. Instead, Akka Persistence 2.4.x introduces an additional (optionally overrideable) -``receivePluginInternal:Actor.Receive`` method in the plugin API, which can be used for handling those as well as any custom messages -that are sent to the plugin Actor (imagine use cases like "wake up and continue reading" or custom protocols which your -specialised journal can implement). - -Implementations using the previous feature should adjust their code as follows:: - - // previously - class MySnapshots extends SnapshotStore { - // old API: - // def saved(meta: SnapshotMetadata): Unit = doThings() - - // new API: - def saveAsync(metadata: SnapshotMetadata, snapshot: Any): Future[Unit] = { - // completion or failure of the returned future triggers internal messages in receivePluginInternal - val f: Future[Unit] = ??? - - // custom messages can be piped to self in order to be received in receivePluginInternal - f.map(MyCustomMessage(_)) pipeTo self - - f - } - - def receivePluginInternal = { - case SaveSnapshotSuccess(metadata) => doThings() - case MyCustomMessage(data) => doOtherThings() - } - - // ... - } - -SnapshotStore: Java 8 Optional used in Java plugin APIs -------------------------------------------------------- -In places where previously ``akka.japi.Option`` was used in Java APIs, including the return type of ``doLoadAsync``, -the Java 8 provided ``Optional`` type is used now. - -Please remember that when creating an ``java.util.Optional`` instance from a (possibly) ``null`` value you will want to -use the non-throwing ``Optional.fromNullable`` method, which converts a ``null`` into a ``None`` value - which is -slightly different than its Scala counterpart (where ``Option.apply(null)`` returns ``None``). - -Atomic writes -------------- - -``asyncWriteMessages`` takes a ``immutable.Seq[AtomicWrite]`` parameter instead of -``immutable.Seq[PersistentRepr]``. - -Each `AtomicWrite` message contains the single ``PersistentRepr`` that corresponds to the event that was -passed to the ``persist`` method of the ``PersistentActor``, or it contains several ``PersistentRepr`` -that corresponds to the events that were passed to the ``persistAll`` method of the ``PersistentActor``. -All ``PersistentRepr`` of the `AtomicWrite` must be written to the data store atomically, i.e. all or -none must be stored. - -If the journal (data store) cannot support atomic writes of multiple events it should -reject such writes with a ``Try`` ``Failure`` with an ``UnsupportedOperationException`` -describing the issue. This limitation should also be documented by the journal plugin. - -Rejecting writes ----------------- - -``asyncWriteMessages`` returns a ``Future[immutable.Seq[Try[Unit]]]``. - -The journal can signal that it rejects individual messages (``AtomicWrite``) by the returned -`immutable.Seq[Try[Unit]]`. The returned ``Seq`` must have as many elements as the input -``messages`` ``Seq``. Each ``Try`` element signals if the corresponding ``AtomicWrite`` -is rejected or not, with an exception describing the problem. Rejecting a message means it -was not stored, i.e. it must not be included in a later replay. Rejecting a message is -typically done before attempting to store it, e.g. because of serialization error. - -Read the :ref:`API documentation ` of this method for more -information about the semantics of rejections and failures. - -asyncReplayMessages Java API ----------------------------- - -The signature of `asyncReplayMessages` in the Java API changed from ``akka.japi.Procedure`` -to ``java.util.function.Consumer``. - -asyncDeleteMessagesTo ---------------------- - -The ``permanent`` deletion flag was removed. Support for non-permanent deletions was -removed. Events that were deleted with ``permanent=false`` with older version will -still not be replayed in this version. - -References to "replay" in names -------------------------------- -Previously a number of classes and methods used the word "replay" interchangeably with the word "recover". -This lead to slight inconsistencies in APIs, where a method would be called ``recovery``, yet the -signal for a completed recovery was named ``ReplayMessagesSuccess``. - -This is now fixed, and all methods use the same "recovery" wording consistently across the entire API. -The old ``ReplayMessagesSuccess`` is now called ``RecoverySuccess``, and an additional method called ``onRecoveryFailure`` -has been introduced. - -AtLeastOnceDelivery deliver signature -------------------------------------- -The signature of ``deliver`` changed slightly in order to allow both ``ActorSelection`` and ``ActorPath`` to be -used with it. - -Previously: - - def deliver(destination: ActorPath, deliveryIdToMessage: Long ⇒ Any): Unit - -Now: - - def deliver(destination: ActorSelection)(deliveryIdToMessage: Long ⇒ Any): Unit - def deliver(destination: ActorPath)(deliveryIdToMessage: Long ⇒ Any): Unit - -The Java API remains unchanged and has simply gained the 2nd overload which allows ``ActorSelection`` to be -passed in directly (without converting to ``ActorPath``). - - -Actor system shutdown ---------------------- -``ActorSystem.shutdown``, ``ActorSystem.awaitTermination`` and ``ActorSystem.isTerminated`` has been -deprecated in favor of ``ActorSystem.terminate`` and ``ActorSystem.whenTerminated```. Both returns a -``Future[Terminated]`` value that will complete when the actor system has terminated. - -To get the same behavior as ``ActorSystem.awaitTermination`` block and wait for ``Future[Terminated]`` value -with ``Await.result`` from the Scala standard library. - -To trigger a termination and wait for it to complete: - - import scala.concurrent.duration._ - Await.result(system.terminate(), 10.seconds) - -Be careful to not do any operations on the ``Future[Terminated]`` using the ``system.dispatcher`` -as ``ExecutionContext`` as it will be shut down with the ``ActorSystem``, instead use for example -the Scala standard library context from ``scala.concurrent.ExecutionContext.global``. - -:: - - // import system.dispatcher <- this would not work - import scala.concurrent.ExecutionContext.Implicits.global - - system.terminate().foreach { _ => - println("Actor system was shut down") - } - +Migration from 2.3.x to 2.4.x is described in the +`documentation of 2.4 `_. \ No newline at end of file diff --git a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst index 1eeadafd5f..99bac62ba3 100644 --- a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst +++ b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst @@ -1,8 +1,8 @@ .. _migration-guide-2.4.x-2.5.x: -####################################### -Upcoming Migration Guide 2.4.x to 2.5.x -####################################### +############################## +Migration Guide 2.4.x to 2.5.x +############################## Akka Streams ============ @@ -79,3 +79,19 @@ A new :ref:`persistence plugin proxy` was added, that non-sharable journal or snapshot store. The proxy is available by setting ``akka.persistence.journal.plugin`` or ``akka.persistence.snapshot-store.plugin`` to ``akka.persistence.journal.proxy`` or ``akka.persistence.snapshot-store.proxy``, respectively. The proxy supplants the :ref:`Shared LevelDB journal`. + + +Cluster +======= + +Cluster Management Command Line Tool +------------------------------------ + +There is a new cluster management tool with HTTP API that has the same functionality as the command line tool. +The HTTP API gives you access to cluster membership information as JSON including full reachability status between the nodes. +It supports the ordinary cluster operations such as join, leave, and down. + +See documentation of `akka/akka-cluster-management `_. + +The command line script for cluster management has been deprecated and is scheduled for removal +in the next major version. Use the HTTP API with `curl `_ or similar instead. 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 index 444dff4ece..e5a923cdeb 100644 --- a/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst +++ b/akka-docs/rst/project/migration-guide-eventsourced-2.3.x.rst @@ -4,188 +4,6 @@ Migration Guide Eventsourced to Akka Persistence 2.3.x ###################################################### -General notes -============= +Migration from Eventsourced to Akka Persistence 2.3.x is described in the +`documentation of 2.4 `_. -`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 `example usage `_). -- `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 - `PersistentActor`` creation. Journal actors are automatically created from a journal plugin configuration (see - :ref:`journal-plugin-api`). -- ``PersistentActor`` can be created like any other actor with ``actorOf`` without using the - ``Persistence`` extension. -- Is **not** a central registry of persistent actors. - -Processors / PersistentActor -============================ - -**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:** ``PersistentActor`` - -- Trait that adds journaling to actors (see :ref:`event-sourcing-scala`) and used by applications for - *event sourcing* or *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-scala` 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. -- Sender references are written to the journal. Sender references of type ``PromiseActorRef`` are - not journaled, they are ``system.deadLetters`` on replay. -- Supports :ref:`snapshots`. -- :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. - -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. - -**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:** ``AtLeastOnceDelivery`` - -- ``AtLeastOnceDelivery`` trait is mixed in to a ``PersistentActor`` -- Does not prevent redundant delivery of messages to a destination entirely, but won't re-send messages whose delivery - is confirmed during recovery. -- 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``). -- Redelivers messages on missing delivery confirmation. 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). - -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 ``PersistentActor`` by reading it directly from the - journal (see :ref:`persistent-views`). Alternative to using channels. Useful in situations where actors shall receive a - persistent message stream in correct order without duplicates. -- 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 persistent actor 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-guide-persistence-experimental-2.3.x-2.4.x.rst b/akka-docs/rst/project/migration-guide-persistence-experimental-2.3.x-2.4.x.rst index 051f7158d3..45034ec502 100644 --- a/akka-docs/rst/project/migration-guide-persistence-experimental-2.3.x-2.4.x.rst +++ b/akka-docs/rst/project/migration-guide-persistence-experimental-2.3.x-2.4.x.rst @@ -4,202 +4,5 @@ Migration Guide Akka Persistence (experimental) 2.3.3 to 2.3.4 (and 2.4.x) ########################################################################## -**Akka Persistence** is an **experimental module**, which means that neither Binary Compatibility nor API stability -is provided for Persistence while under the *experimental* flag. The goal of this phase is to gather user feedback -before we freeze the APIs in a major release. - -defer renamed to deferAsync -=========================== -The ``defer`` method in ``PersistentActor`` was renamed to ``deferAsync`` as it matches the semantics -of ``persistAsync`` more closely than ``persist``, which was causing confusion for users. - -Its semantics remain unchanged. - -Renamed EventsourcedProcessor to PersistentActor -================================================ -``EventsourcedProcessor`` is now deprecated and replaced by ``PersistentActor`` which provides the same (and more) API. -Migrating to ``2.4.x`` is as simple as changing all your classes to extending ``PersistentActor``. - -Replace all classes like:: - - class DeprecatedProcessor extends EventsourcedProcessor { - def processorId = "id" - /*...*/ - } - -To extend ``PersistentActor``:: - - class NewPersistentProcessor extends PersistentActor { - def persistenceId = "id" - /*...*/ - } - -Read more about the persistent actor in the :ref:`documentation for Scala ` and -:ref:`documentation for Java `. - -Changed processorId to (abstract) 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). - -Please note that ``persistenceId`` is **abstract** in the new API classes (``PersistentActor`` and ``PersistentView``), -and we do **not** provide a default (actor-path derived) value for it like we did for ``processorId``. -The rationale behind this change being stricter de-coupling of your Actor hierarchy and the logical "which persistent entity this actor represents". -A longer discussion on this subject can be found on `issue #15436 `_ on github. - -In case you want to preserve the old behavior of providing the actor's path as the default ``persistenceId``, you can easily -implement it yourself either as a helper trait or simply by overriding ``persistenceId`` as follows:: - - override def persistenceId = self.path.toStringWithoutAddress - -We provided the renamed method also on already deprecated classes (Channels), -so you can simply apply a global rename of ``processorId`` to ``persistenceId``. - -Removed Processor in favour of extending PersistentActor with persistAsync -========================================================================== - -The ``Processor`` is now deprecated since ``2.3.4`` and will be removed in ``2.4.x``. -It's semantics replicated in ``PersistentActor`` in the form of an additional ``persist`` method: ``persistAsync``. - -In essence, the difference between ``persist`` and ``persistAsync`` is that the former will stash all incoming commands -until all persist callbacks have been processed, whereas the latter does not stash any commands. The new ``persistAsync`` -should be used in cases of low consistency yet high responsiveness requirements, the Actor can keep processing incoming -commands, even though not all previous events have been handled. - -When these ``persist`` and ``persistAsync`` are used together in the same ``PersistentActor``, the ``persist`` -logic will win over the async version so that all guarantees concerning persist still hold. This will however lower -the throughput - -Now deprecated code using Processor:: - - class OldProcessor extends Processor { - override def processorId = "user-wallet-1337" - - def receive = { - case Persistent(cmd) => sender() ! cmd - } - } - -Replacement code, with the same semantics, using PersistentActor:: - - class NewProcessor extends PersistentActor { - override def persistenceId = "user-wallet-1337" - - def receiveCommand = { - case cmd => - persistAsync(cmd) { e => sender() ! e } - } - - def receiveRecover = { - case _ => // logic for handling replay - } - } - -It is worth pointing out that using ``sender()`` inside the persistAsync callback block is **valid**, and does *not* suffer -any of the problems Futures have when closing over the sender reference. - -Using the ``PersistentActor`` instead of ``Processor`` also shifts the responsibility of deciding if a message should be persisted -to the receiver instead of the sender of the message. Previously, using ``Processor``, clients would have to wrap messages as ``Persistent(cmd)`` -manually, as well as have to be aware of the receiver being a ``Processor``, which didn't play well with transparency of the ActorRefs in general. - -How to migrate data from Processor to PersistentActor ------------------------------------------------------ - -The recommended approach for migrating persisted messages from a ``Processor`` to events that can be replayed by -a ``PersistentActor`` is to write a custom migration tool with a ``PersistentView`` and a ``PersistentActor``. -Connect the ``PersistentView`` to the ``persistenceId`` of the old ``Processor`` to replay the stored persistent -messages. Send the messages from the view to a ``PersistentActor`` with another ``persistenceId``. There you can -transform the old messages to domain events that the real ``PersistentActor`` will be able to understand. Store -the events with ``persistAsync``. - -Note that you can implement back-pressure between the writing ``PersistentActor`` and the reading ``PersistentView`` -by turning off auto-update in the view and send custom ``Update`` messages to the view with a limited `replayMax` -value. - -Removed deleteMessage -===================== - -``deleteMessage`` is deprecated and will be removed. When using command sourced ``Processor`` the command was stored before it was -received and could be validated and then there was a reason to remove faulty commands to avoid repeating the error during replay. -When using ``PersistentActor`` you can always validate the command before persisting and therefore the stored event (or command) -should always be valid for replay. - -``deleteMessages`` can still be used for pruning of all messages up to a sequence number. - - -Renamed View to PersistentView, which receives plain messages (Persistent() wrapper is gone) -============================================================================================ -Views used to receive messages wrapped as ``Persistent(payload, seqNr)``, this is no longer the case and views receive -the ``payload`` as message from the ``Journal`` directly. The rationale here is that the wrapper approach was inconsistent -with the other Akka Persistence APIs and also is not easily "discoverable" (you have to *know* you will be getting this Persistent wrapper). - -Instead, since ``2.3.4``, views get plain messages, and can use additional methods provided by the ``View`` to identify if a message -was sent from the Journal (had been played back to the view). So if you had code like this:: - - class AverageView extends View { - override def processorId = "average-view" - - def receive = { - case Persistent(msg, seqNr) => - // from Journal - - case msg => - // from user-land - } - -You should update it to extend ``PersistentView`` instead:: - - class AverageView extends PersistentView { - override def persistenceId = "persistence-sample" - override def viewId = "persistence-sample-average" - - def receive = { - case msg if isPersistent => - // from Journal - val seqNr = lastSequenceNr // in case you require the sequence number - - case msg => - // from user-land - } - } - -In case you need to obtain the current sequence number the view is looking at, you can use the ``lastSequenceNr`` method. -It is equivalent to "current sequence number", when ``isPersistent`` returns true, otherwise it yields the sequence number -of the last persistent message that this view was updated with. - -Removed Channel and PersistentChannel in favour of AtLeastOnceDelivery trait -============================================================================ - -One of the primary tasks of a ``Channel`` was to de-duplicate messages that were sent from a -``Processor`` during recovery. Performing external side effects during recovery is not -encouraged with event sourcing and therefore the ``Channel`` is not needed for this purpose. - -The ``Channel`` and ``PersistentChannel`` also performed at-least-once delivery of messages, -but it did not free a sending actor from implementing retransmission or timeouts, since the -acknowledgement from the channel is needed to guarantee safe hand-off. Therefore at-least-once -delivery is provided in a new ``AtLeastOnceDelivery`` trait that is mixed-in to the -persistent actor on the sending side. - -Read more about at-least-once delivery in the :ref:`documentation for Scala ` and -:ref:`documentation for Java `. - -Default persistence plugins -=========================== -Previously default ``akka.persistence.journal.plugin`` was set to the LevelDB journal ``akka.persistence.journal.leveldb`` -and default ``akka.persistence.snapshot-store.plugin`` was set to the local file-system snapshot ``akka.persistence.snapshot-store.local``. -Now default journal and default snapshot-store plugins are set to empty "" in the persistence extension ``reference.conf``, -and require explicit user configuration via override in the user ``application.conf``. -This change was needed to decouple persistence extension from the LevelDB dependency, and to support multiple plugin configurations. -Please see persistence extension ``reference.conf`` for details. - -Converted LevelDB to an optional dependency -=========================================== -Persistence extension uses LevelDB based plugins for own development and keeps related code in the published jar. -However previously LevelDB was a ``compile`` scope dependency, and now it is an ``optional;provided`` dependency. -To continue using LevelDB based persistence plugins it is now required for related user projects -to include an additional explicit dependency declaration for the LevelDB artifacts. -This change allows production Akka deployments to avoid need for the LevelDB provisioning. -Please see persistence extension ``reference.conf`` for details. +Migration from Akka Persistence 2.3.3 to 2.3.4 (and 2.4.x) is described in the +`documentation of 2.4 `_. diff --git a/akka-docs/rst/project/sponsors.rst b/akka-docs/rst/project/sponsors.rst index 2f99dbbc7d..b2a158ff27 100644 --- a/akka-docs/rst/project/sponsors.rst +++ b/akka-docs/rst/project/sponsors.rst @@ -11,13 +11,3 @@ Play Web Framework, Scala IDE, sbt and many other open source projects. It also provides the Lightbend Stack, a full-featured development stack consisting of AKka, Play and Scala. Learn more at `lightbend.com `_. - -YourKit -------- - -YourKit is kindly supporting open source projects with its full-featured Java Profiler. - -YourKit, LLC is the creator of innovative and intelligent tools for profiling Java -and .NET applications. Take a look at YourKit’s leading software products: -`YourKit Java Profiler `_ -and `YourKit .NET Profiler `_ diff --git a/akka-docs/rst/scala/cluster-usage.rst b/akka-docs/rst/scala/cluster-usage.rst index 3b13734a3a..ec9aa90d71 100644 --- a/akka-docs/rst/scala/cluster-usage.rst +++ b/akka-docs/rst/scala/cluster-usage.rst @@ -85,7 +85,7 @@ seed nodes in the existing cluster. If you don't configure seed nodes you need to join the cluster programmatically or manually. -Manual joining can be performed by using ref:`cluster_jmx_scala` or :ref:`cluster_command_line_scala`. +Manual joining can be performed by using ref:`cluster_jmx_scala` or :ref:`cluster_http_scala`. Joining programmatically can be performed with ``Cluster(system).join``. Unsuccessful join attempts are automatically retried after the time period defined in configuration property ``retry-unsuccessful-join-after``. Retries can be disabled by setting the property to ``off``. @@ -129,7 +129,7 @@ leader is not allowed to perform its duties, such as changing status of new joining members to 'Up'. The node must first become reachable again, or the status of the unreachable member must be changed to 'Down'. Changing status to 'Down' can be performed automatically or manually. By default it must be done manually, using -:ref:`cluster_jmx_scala` or :ref:`cluster_command_line_scala`. +:ref:`cluster_jmx_scala` or :ref:`cluster_http_scala`. It can also be performed programmatically with ``Cluster(system).down(address)``. @@ -176,7 +176,7 @@ as unreachable and removed after the automatic or manual downing as described above. A more graceful exit can be performed if you tell the cluster that a node shall leave. -This can be performed using :ref:`cluster_jmx_scala` or :ref:`cluster_command_line_scala`. +This can be performed using :ref:`cluster_jmx_scala` or :ref:`cluster_http_scala`. It can also be performed programmatically with: .. includecode:: code/docs/cluster/ClusterDocSpec.scala#leave @@ -690,10 +690,21 @@ the actor system for a specific role. This can also be used to grab the ``akka.a .. includecode:: ../../../akka-samples/akka-sample-cluster-scala/src/multi-jvm/scala/sample/cluster/stats/StatsSampleSpec.scala#addresses +Management +^^^^^^^^^^ + +.. _cluster_http_scala: + +HTTP +---- + +Information and management of the cluster is available with a HTTP API. +See documentation of `akka/akka-cluster-management `_. + .. _cluster_jmx_scala: JMX -^^^ +--- Information and management of the cluster is available as JMX MBeans with the root name ``akka.Cluster``. The JMX information can be displayed with an ordinary JMX console such as JConsole or JVisualVM. @@ -711,8 +722,13 @@ Member nodes are identified by their address, in format `akka.://`_ + or similar instead. The cluster can be managed with the script `bin/akka-cluster` provided in the Akka distribution. @@ -743,13 +759,8 @@ Run it without parameters to see instructions about how to use the script:: To be able to use the script you must enable remote monitoring and management when starting the JVMs of the cluster nodes, -as described in `Monitoring and Management Using JMX Technology `_ - -Example of system properties to enable remote monitoring and management:: - - java -Dcom.sun.management.jmxremote.port=9999 \ - -Dcom.sun.management.jmxremote.authenticate=false \ - -Dcom.sun.management.jmxremote.ssl=false +as described in `Monitoring and Management Using JMX Technology `_. +Make sure you understand the security implications of enabling remote monitoring and management. .. _cluster_configuration_scala: diff --git a/akka-kernel/src/main/dist/bin/akka-cluster b/akka-kernel/src/main/dist/bin/akka-cluster index b2e29c86b2..08fa4401d8 100755 --- a/akka-kernel/src/main/dist/bin/akka-cluster +++ b/akka-kernel/src/main/dist/bin/akka-cluster @@ -44,6 +44,8 @@ function ensureNodeIsRunningAndAvailable { fi } +echo "This tool is deprecated use curl and https://github.com/akka/akka-cluster-management instead, since 2.5.0" + # switch on command case "$1" in