Merge branch 'master' into wip-2053d-actorbased-remote-drewhk

akka-docs/rst/java/code/docs/actor/FaultHandlingTestBase.java

@@ -27,10 +27,11 @@ import akka.testkit.ErrorFilter;
 import akka.testkit.EventFilter;
 import akka.testkit.TestEvent;
 import static java.util.concurrent.TimeUnit.SECONDS;
+import static akka.japi.Util.immutableSeq;
 import akka.japi.Function;
 import scala.Option;
 import scala.collection.JavaConverters;
-import scala.collection.Seq;
+import scala.collection.immutable.Seq;
 
 import org.junit.Test;
 import org.junit.BeforeClass;
@@ -219,8 +220,7 @@ public class FaultHandlingTestBase {
 
   //#testkit
   public <A> Seq<A> seq(A... args) {
-    return JavaConverters.collectionAsScalaIterableConverter(
-      java.util.Arrays.asList(args)).asScala().toSeq();
+    return immutableSeq(args);
   }
   //#testkit
 }

akka-docs/rst/java/code/docs/actor/UntypedActorDocTestBase.java

@@ -351,24 +351,23 @@ public class UntypedActorDocTestBase {
   static
   //#stash
   public class ActorWithProtocol extends UntypedActorWithStash {
-    private Boolean isOpen = false;
     public void onReceive(Object msg) {
-      if (isOpen) {
-        if (msg.equals("write")) {
-          // do writing...
-        } else if (msg.equals("close")) {
-          unstashAll();
-          isOpen = false;
-        } else {
-          stash();
-        }
+      if (msg.equals("open")) {
+        unstashAll();
+        getContext().become(new Procedure<Object>() {
+          public void apply(Object msg) throws Exception {
+            if (msg.equals("write")) {
+              // do writing...
+            } else if (msg.equals("close")) {
+              unstashAll();
+              getContext().unbecome();
+            } else {
+              stash();
+            }
+          }
+        }, false); // add behavior on top instead of replacing
       } else {
-        if (msg.equals("open")) {
-          unstashAll();
-          isOpen = true;
-        } else {
-          stash();
-        }
+        stash();
       }
     }
   }

akka-docs/rst/java/code/docs/actor/UntypedActorSwapper.java

@@ -32,9 +32,9 @@ public class UntypedActorSwapper {
           @Override
           public void apply(Object message) {
             log.info("Ho");
-            getContext().unbecome(); // resets the latest 'become' (just for fun)
+            getContext().unbecome(); // resets the latest 'become'
           }
-        });
+        }, false); // this signals stacking of the new behavior
       } else {
         unhandled(message);
       }

akka-docs/rst/java/code/docs/event/LoggingDocTestBase.java

@@ -119,5 +119,4 @@ public class LoggingDocTestBase {
     }
   }
   //#deadletter-actor
-
 }

akka-docs/rst/java/code/docs/jrouting/CustomRouterDocTestBase.java

@@ -11,6 +11,7 @@ import static docs.jrouting.CustomRouterDocTestBase.Message.RepublicanVote;
 import static org.junit.Assert.assertEquals;
 
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.List;
 
 import org.junit.After;
@@ -69,7 +70,7 @@ public class CustomRouterDocTestBase {
     //#supervision
     final SupervisorStrategy strategy =
       new OneForOneStrategy(5, Duration.create("1 minute"),
-        new Class<?>[] { Exception.class });
+         Collections.<Class<? extends Throwable>>singletonList(Exception.class));
     final ActorRef router = system.actorOf(new Props(MyActor.class)
         .withRouter(new RoundRobinRouter(5).withSupervisorStrategy(strategy)));
     //#supervision
@@ -179,16 +180,14 @@ public class CustomRouterDocTestBase {
       //#crRoutingLogic
       return new CustomRoute() {
         @Override
-        public Iterable<Destination> destinationsFor(ActorRef sender, Object msg) {
+        public scala.collection.immutable.Seq<Destination> destinationsFor(ActorRef sender, Object msg) {
           switch ((Message) msg) {
           case DemocratVote:
           case DemocratCountResult:
-            return Arrays.asList(
-              new Destination[] { new Destination(sender, democratActor) });
+            return akka.japi.Util.immutableSingletonSeq(new Destination(sender, democratActor));
           case RepublicanVote:
           case RepublicanCountResult:
-            return Arrays.asList(
-              new Destination[] { new Destination(sender, republicanActor) });
+            return akka.japi.Util.immutableSingletonSeq(new Destination(sender, republicanActor));
           default:
             throw new IllegalArgumentException("Unknown message: " + msg);
           }

akka-docs/rst/java/untyped-actors.rst

@@ -549,7 +549,8 @@ Upgrade
 
 Akka supports hotswapping the Actor’s message loop (e.g. its implementation) at
 runtime. Use the ``getContext().become`` method from within the Actor.
-The hotswapped code is kept in a Stack which can be pushed and popped.
+The hotswapped code is kept in a Stack which can be pushed (replacing or adding
+at the top) and popped.
 
 .. warning::
 
@@ -563,26 +564,19 @@ To hotswap the Actor using ``getContext().become``:
 .. includecode:: code/docs/actor/UntypedActorDocTestBase.java
    :include: hot-swap-actor
 
-The ``become`` method is useful for many different things, such as to implement
-a Finite State Machine (FSM).
+This variant of the :meth:`become` method is useful for many different things,
+such as to implement a Finite State Machine (FSM). It will replace the current
+behavior (i.e. the top of the behavior stack), which means that you do not use
+:meth:`unbecome`, instead always the next behavior is explicitly installed.
 
-Here is another little cute example of ``become`` and ``unbecome`` in action:
+The other way of using :meth:`become` does not replace but add to the top of
+the behavior stack. In this case care must be taken to ensure that the number
+of “pop” operations (i.e. :meth:`unbecome`) matches the number of “push” ones
+in the long run, otherwise this amounts to a memory leak (which is why this
+behavior is not the default). 
 
 .. includecode:: code/docs/actor/UntypedActorSwapper.java#swapper
 
-Downgrade
----------
-
-Since the hotswapped code is pushed to a Stack you can downgrade the code as
-well. Use the ``getContext().unbecome`` method from within the Actor.
-
-.. code-block:: java
-
-  public void onReceive(Object message) {
-    if (message.equals("revert")) getContext().unbecome();
-  }
-
-
 Stash
 =====
 
@@ -627,9 +621,11 @@ The stash is backed by a ``scala.collection.immutable.Vector``. As a
 result, even a very large number of messages may be stashed without a
 major impact on performance.
 
-Note that the stash is not persisted across restarts of an actor,
-unlike the actor's mailbox. Therefore, it should be managed like other
-parts of the actor's state which have the same property.
+Note that the stash is part of the ephemeral actor state, unlike the
+mailbox. Therefore, it should be managed like other parts of the
+actor's state which have the same property. The :class:`Stash` trait’s
+implementation of :meth:`preRestart` will call ``unstashAll()``, which is
+usually the desired behavior.
 
 
 Killing an Actor