change Java stash sample to become(), see #2642

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/untyped-actors.rst

@@ -627,9 +627,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

akka-docs/rst/scala/actors.rst

@@ -752,9 +752,11 @@ major impact on performance.
   callback. This means it's not possible to write
   ``Actor with MyActor with Stash`` if ``MyActor`` overrides ``preRestart``.
 
-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