raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Merge pull request #929 from richdougherty/wip-2773-edit-migration-guide

Browse source 
Add intro to migration guide and do a minor edit. Fixes #2773
This commit is contained in:
Roland Kuhn 2012-12-10 05:09:52 -08:00
commit 761f1c6258
1 changed files with 55 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

99
akka-docs/rst/project/migration-guide-2.0.x-2.1.x.rst
View file

@ -4,27 +4,35 @@
Migration Guide 2.0.x to 2.1.x
################################
The 2.1 release contains several structural changes that require some
simple, mechanical source-level changes in client code. Several things have
been moved to Scala standard library, such as ``Future``, and some package
names have been changed in Remoting and Durable Mailboxes.
Some parts of the 2.0 API have changed in the Akka 2.1 release. This guide lists the the changes and
explains what you will need to do to upgrade your program to work with Akka 2.1.
When migrating from 1.3.x to 2.1.x you should first follow the instructions for
migrating `1.3.x to 2.0.x <http://doc.akka.io/docs/akka/2.0.3/project/migration-guide-1.3.x-2.0.x.html>`_.
Migrating from Akka 2.0.x to Akka 2.1.x is relatively straightforward. In Akka 2.1 the API has
undergone some basic housekeeping, for example some package names have changed, but otherwise usage
is largely unchanged. User programs will generally only need simple, mechanical changes in order to
work with Akka 2.1.
If you are migrating from Akka 1.3.x you will need to follow the instructions for
`migrating from Akka 1.3.x to 2.0.x <http://doc.akka.io/docs/akka/2.0.3/project/migration-guide-1.3.x-2.0.x.html>`_
before following the instructions in this guide.
Scala Version
=============
Akka 2.1 uses a new version of Scala.
Change your project build and dependencies to Scala version ``@scalaVersion@``.
Config Dependency
=================
`Typesafe config <https://github.com/typesafehub/config>`_ library is a normal
dependency of akka-actor and it is no longer embedded in ``akka-actor.jar``.
If your are using a build tool with dependency resolution, such as sbt or maven you
will not notice the difference, but if you have manually constructed classpaths
you need to add `config-1.0.0.jar <http://mirrors.ibiblio.org/maven2/com/typesafe/config/1.0.0/>`_.
Akka's configuration system has graduated from Akka to become the `Typesafe config
<https://github.com/typesafehub/config>`_ project. The configuration system was previously embedded
within ``akka-actor.jar``, now it is specified as a dependency of ``akka-actor.jar``.
If your are using a build tool with automatic dependency resolution, such as sbt or Maven, then you
will not notice a difference. Otherwise you will need to ensure that
`config-1.0.0.jar <http://mirrors.ibiblio.org/maven2/com/typesafe/config/1.0.0/>`_
is present on your classpath.
Pieces Moved to Scala Standard Library
======================================
@ -48,7 +56,8 @@ Search Replace with
Scheduler Dispatcher
====================
The ``ExecutionContext`` to use for running scheduled tasks must be specified.
The ``ExecutionContext`` to use for running scheduled tasks must now be specified.
You can use an Akka ``Dispatcher`` for this purpose.
Scala:
@ -80,7 +89,7 @@ Java:
}, system.dispatcher());
API Changes of Future - Scala
API Changes to Future - Scala
=============================
v2.0::
@ -106,7 +115,7 @@ v2.1::
API Changes of Future - Java
API Changes to Future - Java
============================
v2.0::
@ -182,17 +191,17 @@ v2.1::
}
}, ec);
API changes of DynamicAccess
API changes to DynamicAccess
============================
All methods with scala.Either[Throwable, X] have been changed to used scala.util.Try[X].
All methods with scala.Either[Throwable, X] have been changed to use scala.util.Try[X].
DynamicAccess.withErrorHandling has been removed since scala.util.Try now fulfills that role.
API changes of Serialization
API changes to Serialization
============================
All methods with scala.Either[Throwable, X] have been changed to used scala.util.Try[X].
All methods with scala.Either[Throwable, X] have been changed to use scala.util.Try[X].
Empty Props
===========
@ -231,14 +240,14 @@ v2.1 Scala::
Failing Send
============
When failing to send to a remote actor or actor with bounded or durable mailbox the message will
silently be delivered to ``ActorSystem.deadletters`` instead of throwing an exception.
When failing to send to a remote actor or an actor with a bounded or durable mailbox the message will
now be silently delivered to ``ActorSystem.deadletters`` instead of throwing an exception.
Graceful Stop Exception
=======================
If the target actor of ``akka.pattern.gracefulStop`` isn't terminated within the
timeout the ``Future`` is completed with failure ``akka.pattern.AskTimeoutException``.
timeout then the ``Future`` is completed with a failure of ``akka.pattern.AskTimeoutException``.
In 2.0 it was ``akka.actor.ActorTimeoutException``.
getInstance for Singletons - Java
@ -276,23 +285,23 @@ v2.1::
log-remote-lifecycle-events
===========================
Default value of akka.remote.log-remote-lifecycle-events has changed to **on**.
If you don't want these in the log you need to add this to your configuration::
The default value of akka.remote.log-remote-lifecycle-events has changed to **on**.
If you don't want these events in the log then you need to add this to your configuration::
akka.remote.log-remote-lifecycle-events = off
Stash postStop
==============
Both Actors and UntypedActors using ``Stash`` now overrides postStop to make sure that
stashed messages are put into the dead letters when the actor stops, make sure you call
Both Actors and UntypedActors using ``Stash`` now override postStop to make sure that
stashed messages are put into the dead letters when the actor stops. Make sure you call
super.postStop if you override it.
Forward of Terminated message
=============================
Forwarding Terminated messages
==============================
Forward of ``Terminated`` message is no longer supported. Instead, if you forward
``Terminated`` you should send the information in you own message.
Forwarding ``Terminated`` messages is no longer supported. Instead, if you forward
``Terminated`` you should send the information in your own message.
v2.0::
@ -313,12 +322,12 @@ v2.1::
}
Custom Router or Resizer
========================
Custom Routers and Resizers
===========================
The API of ``RouterConfig``, ``RouteeProvider`` and ``Resizer`` has been
cleaned up. If you use these to build your own router functionality the
compiler will tell you you to do some adjustments.
compiler will tell you if you need to make adjustments.
v2.0::
@ -363,19 +372,20 @@ v2.1::
Duration and Timeout
====================
The Duration class in the scala library is an improved version of the previous
:class:`akka.util.Duration`. Among others it keeps the static type of
:class:`FiniteDuration` more consistently, which has been used to tighten APIs.
The advantage is that instead of runtime exceptions you’ll get compiler errors
telling you if you try to pass a possibly non-finite duration where it does not
belong.
The :class:`akka.util.Duration` class has been moved into the Scala library under
the ``scala.concurrent.duration`` package. Several changes have been made to tighten
up the duration and timeout API.
:class:`FiniteDuration` is now used more consistently throught the API.
The advantage is that if you try to pass a possibly non-finite duration where
it does not belong you’ll get compile errors instead of runtime exceptions.
The main source incompatibility is that you may have to change the declared
type of fields from ``Duration`` to ``FiniteDuration`` (factory methods already
return the more precise type wherever possible).
Another change is that ``Duration.parse`` was not accepted by the scala-library
maintainers, use ``Duration.create`` instead.
Another change is that ``Duration.parse`` was not accepted by the Scala library
maintainers; use ``Duration.create`` instead.
v2.0::
@ -393,7 +403,8 @@ Package Name Changes in Remoting
The package name of all classes in the ``akka-remote.jar`` artifact now starts with ``akka.remote``.
This has been done to enable OSGi bundles that don't have conflicting package names.
Change the following import statements. Please note that the serializers are often referenced from configuration.
Change the following import statements. Please note that serializers are often referenced from
configuration files.
Search -> Replace with::
@ -410,7 +421,7 @@ Search -> Replace with::
Package Name Changes in Durable Mailboxes
=========================================
The package name of all classes in the ``akka-file-mailbox.jar`` artifact now starts with ``akka.actor.mailbox.filebased``.
The package names of all classes in the ``akka-file-mailbox.jar`` artifact now start with ``akka.actor.mailbox.filebased``.
This has been done to enable OSGi bundles that don't have conflicting package names.
Change the following import statements. Please note that the ``FileBasedMailboxType`` is often referenced from configuration.
@ -434,7 +445,7 @@ Actor Receive Timeout
=====================
The API for setting and querying the receive timeout has been made more
consisten in always taking and returning a ``Duration``, the wrapping in
consistent in always taking and returning a ``Duration``; the wrapping in
``Option`` has been removed.
(Samples for Java, Scala sources are affected in exactly the same way.)
@ -456,7 +467,7 @@ v2.1::
ConsistentHash
==============
``akka.routing.ConsistentHash`` has been changed to an immutable data structure.
``akka.routing.ConsistentHash`` has been changed into an immutable data structure.
v2.0::