Akka/Scala example source code file (migration-guide-2.2.x-2.3.x.rst)

This example Akka source code file (migration-guide-2.2.x-2.3.x.rst) is included in my "Source Code Warehouse" project. The intent of this project is to help you more easily find Akka and Scala source code examples by using tags.

All credit for the original source code belongs to akka.io; I'm just trying to make examples easier to find. (For my Scala work, see my Scala examples and tutorials.)

Akka tags/keywords

akka, api, deprecated, java, remoting, removed, scala, stm, the, this

The migration-guide-2.2.x-2.3.x.rst Akka example source code

.. _migration-2.3:

################################
 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 <migration-2.0>` and then :ref:`2.0.x to 2.1.x <migration-2.1>`
and then :ref:`2.1.x to 2.2.x <migration-2.2>`.

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 <routing-scala>` and 
:ref:`documentation for Java <routing-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 <https://github.com/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 <persistence-scala>` and 
:ref:`documentation for Java <persistence-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 <http://doc.akka.io/docs/akka/2.2.3/project/migration-guide-2.1.x-2.2.x.html#event-handlers_renamed_to_loggers>`_ 
 * `API changes to FSM and TestFSMRef <http://doc.akka.io/docs/akka/2.2.3/project/migration-guide-2.1.x-2.2.x.html#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 <cluster_subscriber_scala>` and 
:ref:`documentation for Java <cluster_subscriber_java>`.


BalancingDispatcher is Deprecated
=================================

Use ``BalancingPool`` instead of ``BalancingDispatcher``. See :ref:`documentation for Scala <balancing-pool-scala>` and 
:ref:`documentation for Java <balancing-pool-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 <https://github.com/sbt/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