From 5a9be1be06bbe2dd31ea1d2df395ce5893ae4731 Mon Sep 17 00:00:00 2001 From: Viktor Klang Date: Fri, 20 May 2011 13:37:28 +0200 Subject: [PATCH] Adding the migration guide from 0.10 to 1.0 closing ticket #871 --- .../project/migration-guide-0.10.x-1.0.x.rst | 447 ++++++++++++++++++ akka-docs/project/migration-guides.rst | 1 + 2 files changed, 448 insertions(+) create mode 100644 akka-docs/project/migration-guide-0.10.x-1.0.x.rst diff --git a/akka-docs/project/migration-guide-0.10.x-1.0.x.rst b/akka-docs/project/migration-guide-0.10.x-1.0.x.rst new file mode 100644 index 0000000000..5cdbbfd608 --- /dev/null +++ b/akka-docs/project/migration-guide-0.10.x-1.0.x.rst @@ -0,0 +1,447 @@ +Migration guide from 0.10.x to 1.0.x +==================================== + +Akka & Akka Modules separated into two different repositories and distributions +------------------------------------------------------------------------------- + +Akka is split up into two different parts: +* Akka - Reflects all the sections under 'Scala API' and 'Java API' in the navigation bar. +* Akka Modules - Reflects all the sections under 'Add-on modules' in the navigation bar. + +Download the release you need (Akka core or Akka Modules) from ``_ and unzip it. + +---- + +Changed Akka URI +---------------- + +http:*akkasource.org changed to http:*akka.io + +Reflects XSDs, Maven repositories, ScalaDoc etc. + +---- + +Removed 'se.scalablesolutions' prefix +------------------------------------- + +We have removed some boilerplate by shortening the Akka package from +**se.scalablesolutions.akka** to just **akka** so just do a search-replace in your project, +we apologize for the inconvenience, but we did it for our users. + +---- + +Akka-core is no more +-------------------- + +Akka-core has been split into akka-actor, akka-stm, akka-typed-actor & akka-remote this means that you need to update any deps you have on akka-core. + +---- + +Config +------ + +Turning on/off modules +^^^^^^^^^^^^^^^^^^^^^^ + +All the 'service = on' elements for turning modules on and off have been replaced by a top-level list of the enabled services. + +Services available for turning on/off are: +* "remote" +* "http" +* "camel" + +**All** services are **OFF** by default. Enable the ones you are using. + +.. code-block:: ruby + + akka { + enabled-modules = [] # Comma separated list of the enabled modules. Options: ["remote", "camel", "http"] + } + +Renames +^^^^^^^ + +* 'rest' section - has been renamed to 'http' to align with the module name 'akka-http'. +* 'storage' section - has been renamed to 'persistence' to align with the module name 'akka-persistence'. + +.. code-block:: ruby + + akka { + http { + .. + } + + persistence { + .. + } + } + +---- + +Important changes from RC2-RC3 +------------------------------ + +**akka.config.SupervisionSupervise** + +**Scala** + +.. code-block:: scala + + def apply(actorRef: ActorRef, lifeCycle: LifeCycle, registerAsRemoteService: Boolean = false) + +- boolean instead of remoteAddress, registers that actor with it's id as service name on the local server + +**akka.actor.Actors now is the API for Java to interact with Actors, Remoting and ActorRegistry:** + +**Java** + +.. code-block:: java + + import static akka.actor.Actors.*; // <-- The important part + + actorOf(); + remote().actorOf(); + registry().actorsFor("foo"); + +***akka.actor.Actor now is the API for Scala to interact with Actors, Remoting and ActorRegistry:*** + +**Scala** + +.. code-block:: scala + + import akka.actor.Actor._ // <-- The important part + + actorOf().method + remote.actorOf() + registry.actorsFor("foo") + +**object UntypedActor has been deleted and replaced with akka.actor.Actors/akka.actor.Actor (Java/Scala)** + +- UntypedActor.actorOf -> Actors.actorOf (Java) or Actor.actorOf (Scala) + +**object ActorRegistry has been deleted and replaced with akka.actor.Actors.registry()/akka.actor.Actor.registry (Java/Scala)** + +- ActorRegistry. -> Actors.registry(). (Java) or Actor.registry. (Scala) + +**object RemoteClient has been deleted and replaced with akka.actor.Actors.remote()/akka.actor.Actor.remote (Java/Scala)** + +- RemoteClient -> Actors.remote() (Java) or Actor.remote (Scala) + +**object RemoteServer has been deleted and replaced with akka.actor.Actors.remote()/akka.actor.Actor.remote (Java/Scala)** + +- RemoteServer - deleted -> Actors.remote() (Java) or Actor.remote (Scala) + +**classes RemoteActor, RemoteUntypedActor and RemoteUntypedConsumerActors has been deleted and replaced with akka.actor.Actors.remote().actorOf(x, host port)/akka.actor.Actor.remote.actorOf(x, host, port)** + +- RemoteActor, RemoteUntypedActor - deleted, use: remote().actorOf(YourActor.class, host, port) (Java) or remote.actorOf[YourActor](host, port) + +**Remoted spring-actors now default to spring id as service-name, use "service-name" attribute on "remote"-tag to override** + +**Listeners for RemoteServer and RemoteClient** are now registered on Actors.remote().addListener (Java) or Actor.remote.addListener (Scala), this means that all listeners get all remote events, both remote server evens and remote client events, **so adjust your code accordingly.** + +**ActorRef.startLinkRemote has been removed since one specified on creation wether the actor is client-managed or not.** + +Important change from RC3 to RC4 +-------------------------------- + +The Akka-Spring namespace has changed from akkasource.org and scalablesolutions.se to http:*akka.io/schema and http:*akka.io/akka-.xsd + +Module akka-actor +----------------- + +The Actor.init callback has been renamed to "preStart" to align with the general callback naming and is more clear about when it's called. + +The Actor.shutdown callback has been renamed to "postStop" to align with the general callback naming and is more clear about when it's called. + +The Actor.initTransactionalState callback has been removed, logic should be moved to preStart and be wrapped in an atomic block + +**se.scalablesolutions.akka.config.ScalaConfig** and **se.scalablesolutions.akka.config.JavaConfig** have been merged into **akka.config.Supervision** + +**RemoteAddress** has moved from **se.scalablesolutions.akka.config.ScalaConfig** to **akka.config** + +The ActorRef.lifeCycle has changed signature from Option[LifeCycle] to LifeCycle, this means you need to change code that looks like this: +**self.lifeCycle = Some(LifeCycle(Permanent))** to **self.lifeCycle = Permanent** + +The equivalent to **self.lifeCycle = None** is **self.lifeCycle = UndefinedLifeCycle** +**LifeCycle(Permanent)** becomes **Permanent** +**new LifeCycle(permanent())** becomes **permanent()** (need to do: import static se.scalablesolutions.akka.config.Supervision.*; first) + +**JavaConfig.Component** and **ScalaConfig.Component** have been consolidated and renamed as **Supervision.SuperviseTypedActor** + +**self.trapExit** has been moved into the FaultHandlingStrategy, and **ActorRef.faultHandler** has switched type from Option[FaultHandlingStrategy] +to FaultHandlingStrategy: + +**Scala** + +.. code-block:: scala + + import akka.config.Supervision._ + + self.faultHandler = OneForOneStrategy(List(classOf[Exception]), 3, 5000) + +**Java** + +.. code-block:: java + + import static akka.Supervision.*; + + getContext().setFaultHandler(new OneForOneStrategy(new Class[] { Exception.class },50,1000)) + +**RestartStrategy, AllForOne, OneForOne** have been replaced with **AllForOneStrategy** and **OneForOneStrategy** in **se.scalablesolutions.akka.config.Supervision** + +**Scala** + +.. code-block:: scala + + import akka.config.Supervision._ + SupervisorConfig( + OneForOneStrategy(List(classOf[Exception]), 3, 5000), + Supervise(pingpong1,Permanent) :: Nil + ) + +**Java** + +.. code-block:: java + + import static akka.Supervision.*; + + new SupervisorConfig( + new OneForOneStrategy(new Class[] { Exception.class },50,1000), + new Server[] { new Supervise(pingpong1, permanent()) } + ) + +***We have removed the following factory methods:*** + +**Actor.actor { case foo => bar }** +**Actor.transactor { case foo => bar }** +**Actor.temporaryActor { case foo => bar }** +**Actor.init {} receive { case foo => bar }** + +They started the actor and no config was possible, it was inconsistent and irreparable. + +replace with your own factories, or: + +**Scala** + +.. code-block:: scala + + actorOf( new Actor { def receive = { case foo => bar } } ).start + actorOf( new Actor { self.lifeCycle = Temporary; def receive = { case foo => bar } } ).start + +ReceiveTimeout is now rescheduled after every message, before there was only an initial timeout. +To stop rescheduling of ReceiveTimeout, set **receiveTimeout = None** + +HotSwap +------- + +HotSwap does no longer use behavior stacking by default, but that is an option to both "become" and HotSwap. + +HotSwap now takes for Scala a Function from ActorRef to a Receive, the ActorRef passed in is the reference to self, so you can do self.reply() etc. + +---- + +Module akka-stm +--------------- + +The STM stuff is now in its own module. This means that there is no support for transactions or transactors in akka-actor. + +Local and global +^^^^^^^^^^^^^^^^ + +The **local/global** distinction has been dropped. This means that if the following general import was being used: + +**Scala** + +.. code-block:: scala + + import akka.stm.local._ + +this is now just: + +**Scala** + +.. code-block:: scala + + import akka.stm._ + +Coordinated is the new global +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There is a new explicit mechanism for coordinated transactions. See the `Scala Transactors `_ and `Java Transactors `_ documentation for more information. Coordinated transactions and transactors are found in the ``akka.transactor`` package now. The usage of transactors has changed. + +Agents +^^^^^^ + +Agent is now in the akka-stm module and has moved to the ``akka.agent`` package. The implementation has been reworked and is now closer to Clojure agents. There is not much difference in general usage, the main changes involve interaction with the STM. + +While updates to Agents are asynchronous, the state of an Agent is always immediately available for reading by any thread. Agents are integrated with the STM - any dispatches made in a transaction are held until that transaction commits, and are discarded if it is retried or aborted. There is a new ``sendOff`` method for long-running or blocking update functions. + +---- + +Module akka-camel +----------------- + +Access to the CamelService managed by CamelServiceManager has changed: + +* Method service renamed to mandatoryService (Scala) +* Method service now returns Option[CamelService] (Scala) +* Introduced method getMandatoryService() (Java) +* Introduced method getService() (Java) + +**Scala** + +.. code-block:: scala + + import se.scalablesolutions.akka.camel.CamelServiceManager._ + import se.scalablesolutions.akka.camel.CamelService + + val o: Option[CamelService] = service + val s: CamelService = mandatoryService + +**Java** + +.. code-block:: java + + import se.scalablesolutions.akka.camel.CamelService; + import se.scalablesolutions.akka.japi.Option; + import static se.scalablesolutions.akka.camel.CamelServiceManager.*; + + Option o = getService(); + CamelService s = getMandatoryService(); + +Access to the CamelContext and ProducerTemplate managed by CamelContextManager has changed: + +* Method context renamed to mandatoryContext (Scala) +* Method template renamed to mandatoryTemplate (Scala) +* Method service now returns Option[CamelContext] (Scala) +* Method template now returns Option[ProducerTemplate] (Scala) +* Introduced method getMandatoryContext() (Java) +* Introduced method getContext() (Java) +* Introduced method getMandatoryTemplate() (Java) +* Introduced method getTemplate() (Java) + +**Scala** + +.. code-block:: scala + + import org.apache.camel.CamelContext + import org.apache.camel.ProducerTemplate + + import se.scalablesolutions.akka.camel.CamelContextManager._ + + val co: Option[CamelContext] = context + val to: Option[ProducerTemplate] = template + + val c: CamelContext = mandatoryContext + val t: ProducerTemplate = mandatoryTemplate + +**Java** + +.. code-block:: java + + import org.apache.camel.CamelContext; + import org.apache.camel.ProducerTemplate; + + import se.scalablesolutions.akka.japi.Option; + import static se.scalablesolutions.akka.camel.CamelContextManager.*; + + Option co = getContext(); + Option to = getTemplate(); + + CamelContext c = getMandatoryContext(); + ProducerTemplate t = getMandatoryTemplate(); + +The following methods have been renamed on class se.scalablesolutions.akka.camel.Message: + +* bodyAs(Class) has been renamed to getBodyAs(Class) +* headerAs(String, Class) has been renamed to getHeaderAs(String, Class) + +The API for waiting for consumer endpoint activation and de-activation has been changed + +* CamelService.expectEndpointActivationCount has been removed and replaced by CamelService.awaitEndpointActivation +* CamelService.expectEndpointDeactivationCount has been removed and replaced by CamelService.awaitEndpointDeactivation + +**Scala** + +.. code-block:: scala + + import se.scalablesolutions.akka.actor.Actor + import se.scalablesolutions.akka.camel.CamelServiceManager._ + + val s = startCamelService + val actor = Actor.actorOf[SampleConsumer] + + // wait for 1 consumer being activated + s.awaitEndpointActivation(1) { + actor.start + } + + // wait for 1 consumer being de-activated + s.awaitEndpointDeactivation(1) { + actor.stop + } + + s.stop + +**Java** + +.. code-block:: java + + import java.util.concurrent.TimeUnit; + import se.scalablesolutions.akka.actor.ActorRef; + import se.scalablesolutions.akka.actor.Actors; + import se.scalablesolutions.akka.camel.CamelService; + import se.scalablesolutions.akka.japi.SideEffect; + import static se.scalablesolutions.akka.camel.CamelServiceManager.*; + + CamelService s = startCamelService(); + final ActorRef actor = Actors.actorOf(SampleUntypedConsumer.class); + + // wait for 1 consumer being activated + s.awaitEndpointActivation(1, new SideEffect() { + public void apply() { + actor.start(); + } + }); + + // wait for 1 consumer being de-activated + s.awaitEndpointDeactivation(1, new SideEffect() { + public void apply() { + actor.stop(); + } + }); + + s.stop(); + +Module Akka-Http +---------------- + +Atmosphere support has been removed. If you were using akka.comet.AkkaServlet for Jersey support only, +you can switch that to: akka.http.AkkaRestServlet and it should work just like before. + +Atmosphere has been removed because we have a new async http support in the form of Akka Mist, a very thin bridge +between Servlet3.0/JettyContinuations and Actors, enabling Http-as-messages, read more about it here: +http://doc.akka.io/http#Mist%20-%20Lightweight%20Asynchronous%20HTTP + +If you really need Atmosphere support, you can add it yourself by following the steps listed at the start of: +http://doc.akka.io/comet + +Module akka-spring +------------------ + +The Akka XML schema URI has changed to http://akka.io/schema/akka + +.. code-block:: xml + + + + + + \ No newline at end of file diff --git a/akka-docs/project/migration-guides.rst b/akka-docs/project/migration-guides.rst index bf43d939d5..7eb063811c 100644 --- a/akka-docs/project/migration-guides.rst +++ b/akka-docs/project/migration-guides.rst @@ -7,6 +7,7 @@ Migration Guides :maxdepth: 1 migration-guide-1.0.x-1.1.x + migration-guide-0.10.x-1.0.x migration-guide-0.9.x-0.10.x migration-guide-0.8.x-0.9.x migration-guide-0.7.x-0.8.x