docs for ask/pipeTo patterns

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

@@ -37,6 +37,17 @@ import akka.util.Duration;
 import akka.actor.ActorTimeoutException;
 //#import-gracefulStop
 
+//#import-askPipeTo
+import static akka.pattern.Patterns.ask;
+import static akka.pattern.Patterns.pipeTo;
+import akka.dispatch.Future;
+import akka.dispatch.Futures;
+import akka.util.Duration;
+import akka.util.Timeout;
+import java.util.concurrent.TimeUnit;
+import java.util.ArrayList;
+//#import-askPipeTo
+
 import akka.actor.Props;
 import akka.actor.UntypedActor;
 import akka.actor.UntypedActorFactory;
@@ -45,6 +56,8 @@ import akka.dispatch.MessageDispatcher;
 import org.junit.Test;
 import scala.Option;
 import java.lang.Object;
+import java.util.ArrayList;
+import java.util.Iterator;
 import java.util.concurrent.TimeUnit;
 import akka.pattern.Patterns;
 
@@ -198,6 +211,43 @@ public class UntypedActorDocTestBase {
     //#gracefulStop
     system.shutdown();
   }
+  
+  class Result {
+    final int x;
+    final String s;
+    public Result(int x, String s) {
+      this.x = x;
+      this.s = s;
+    }
+  }
+  
+  @Test
+  public void usePatternsAskPipeTo() {
+    ActorSystem system = ActorSystem.create("MySystem");
+    ActorRef actorA = system.actorOf(new Props(MyUntypedActor.class));
+    ActorRef actorB = system.actorOf(new Props(MyUntypedActor.class));
+    ActorRef actorC = system.actorOf(new Props(MyUntypedActor.class));
+    //#ask-pipeTo
+    final Timeout t = new Timeout(Duration.create(5, TimeUnit.SECONDS));
+    
+    final ArrayList<Future<Object>> futures = new ArrayList<Future<Object>>();
+    futures.add(ask(actorA, "request")); // using `akka.actor.timeout` from config
+    futures.add(ask(actorB, "reqeest", t)); // using explicit timeout from above
+    
+    final Future<Iterable<Object>> aggregate = Futures.sequence(futures, system.dispatcher());
+    
+    final Future<Result> transformed = aggregate.map(new akka.japi.Function<Iterable<Object>, Result>() {
+      public Result apply(Iterable<Object> coll) {
+        final Iterator<Object> it = coll.iterator();
+        final String s = (String) it.next();
+        final int x = (Integer) it.next();
+        return new Result(x, s);
+      }
+    });
+    
+    pipeTo(transformed, actorC);
+    //#ask-pipeTo
+  }
 
   public static class MyActor extends UntypedActor {
 

akka-docs/java/untyped-actors.rst

@@ -315,26 +315,37 @@ If invoked without the sender parameter the sender will be
 Ask: Send-And-Receive-Future
 ----------------------------
 
-Using ``?`` will send a message to the receiving Actor asynchronously and
-will immediately return a :class:`Future` which will be completed with
-an ``akka.actor.AskTimeoutException`` after the specified timeout:
+The ``ask`` pattern involves actors as well as futures, hence it is offered as
+a use pattern rather than a method on :class:`ActorRef`:
 
-.. code-block:: java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#import-askPipeTo
 
-  long timeoutMillis = 1000;
-  Future future = actorRef.ask("Hello", timeoutMillis);
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#ask-pipeTo
 
-The receiving actor should reply to this message, which will complete the
-future with the reply message as value; ``getSender.tell(result)``.
+This example demonstrates ``ask`` together with the ``pipeTo`` pattern on
+futures, because this is likely to be a common combination. Please note that
+all of the above is completely non-blocking and asynchronous: ``ask`` produces
+a :class:`Future`, two of which are composed into a new future using the
+:meth:`Futures.sequence` and :meth:`map` methods and then ``pipeTo`` installs
+an ``onComplete``-handler on the future to effect the submission of the
+aggregated :class:`Result` to another actor.
+
+Using ``ask`` will send a message to the receiving Actor as with ``tell``, and
+the receiving actor must reply with ``getSender().tell(reply)`` in order to
+complete the returned :class:`Future` with a value. The ``ask`` operation
+involves creating an internal actor for handling this reply, which needs to
+have a timeout after which it is destroyed in order not to leak resources; see
+more below.
 
 To complete the future with an exception you need send a Failure message to the sender.
-This is not done automatically when an actor throws an exception while processing a
+This is *not done automatically* when an actor throws an exception while processing a
 message.
 
 .. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#reply-exception
 
 If the actor does not complete the future, it will expire after the timeout period,
-specified as parameter to the ``ask`` method.
+specified as parameter to the ``ask`` method; this will complete the
+:class:`Future` with an :class:`AskTimeoutException`.
 
 See :ref:`futures-java` for more information on how to await or query a
 future.
@@ -353,15 +364,6 @@ Gives you a way to avoid blocking.
   there is not yet a way to detect these illegal accesses at compile time. See also:
   :ref:`jmm-shared-state`
 
-The future returned from the ``ask`` method can conveniently be passed around or
-chained with further processing steps, but sometimes you just need the value,
-even if that entails waiting for it (but keep in mind that waiting inside an
-actor is prone to dead-locks, e.g. if obtaining the result depends on
-processing another message on this actor).
-
-.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
-   :include: import-future,using-ask
-
 Forward message
 ---------------