From e18d591647837dfd43aa9c4b73853edad9971e18 Mon Sep 17 00:00:00 2001
From: phaller <philipp.haller@typesafe.com>
Date: Fri, 22 Jun 2012 18:20:29 +0200
Subject: [PATCH] Stash: add Java docs

---
 .../docs/actor/UntypedActorDocTestBase.java   | 29 +++++++++++++
 akka-docs/java/untyped-actors.rst             | 42 +++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java b/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
index c82ce30661..c2fb455cfb 100644
--- a/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
+++ b/akka-docs/java/code/docs/actor/UntypedActorDocTestBase.java
@@ -50,6 +50,10 @@ import java.util.concurrent.TimeUnit;
 import java.util.ArrayList;
 //#import-askPipe
 
+//#import-stash
+import akka.actor.UntypedActorWithStash;
+//#import-stash
+
 import akka.actor.Props;
 import akka.actor.UntypedActor;
 import akka.actor.UntypedActorFactory;
@@ -346,6 +350,31 @@ public class UntypedActorDocTestBase {
 
   //#hot-swap-actor
 
+  //#stash
+  public static 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();
+        }
+      } else {
+        if (msg.equals("open")) {
+          unstashAll();
+          isOpen = true;
+        } else {
+          stash();
+        }
+      }
+    }
+  }
+  //#stash
+
   //#watch
   public static class WatchActor extends UntypedActor {
     final ActorRef child = this.getContext().actorOf(Props.empty(), "child");
diff --git a/akka-docs/java/untyped-actors.rst b/akka-docs/java/untyped-actors.rst
index 31a0df9674..c99b5f2984 100644
--- a/akka-docs/java/untyped-actors.rst
+++ b/akka-docs/java/untyped-actors.rst
@@ -565,6 +565,48 @@ well. Use the ``getContext().unbecome`` method from within the Actor.
     if (message.equals("revert")) getContext().unbecome();
   }
 
+
+Stash
+=====
+
+The ``UntypedActorWithStash`` class enables an actor to temporarily stash away messages
+that can not or should not be handled using the actor's current
+behavior. Upon changing the actor's message handler, i.e., right
+before invoking ``getContext().become()`` or ``getContext().unbecome()``, all
+stashed messages can be "unstashed", thereby prepending them to the actor's
+mailbox. This way, the stashed messages can be processed in the same
+order as they have been received originally.
+
+.. warning::
+
+  Please note that the stash can only be used together with actors
+  that have a deque-based mailbox. For this, configure the
+  ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as
+  ``akka.dispatch.UnboundedDequeBasedMailbox``.
+
+Here is an example of the ``UntypedActorWithStash`` class in action:
+
+.. includecode:: code/docs/actor/UntypedActorDocTestBase.java#stash
+
+Invoking ``stash()`` adds the current message (the message that the
+actor received last) to the actor's stash. It is typically invoked
+when handling the default case in the actor's message handler to stash
+messages that aren't handled by the other cases. It is illegal to
+stash the same message twice; to do so results in a
+``IllegalStateException`` being thrown. The stash may also be bounded
+in which case invoking ``stash()`` may lead to a capacity violation,
+which results in a ``StashOverflowException``. The capacity of the
+stash can be configured using the ``stash-capacity`` setting (an ``Int``) of the
+dispatcher's configuration.
+
+Invoking ``unstashAll()`` enqueues messages from the stash to the
+actor's mailbox until the capacity of the mailbox (if any) has been
+reached (note that messages from the stash are prepended to the
+mailbox). In case a bounded mailbox overflows, a
+``MessageQueueAppendFailedException`` is thrown.
+The stash is guaranteed to be empty after calling ``unstashAll()``.
+
+
 Killing an Actor
 ================