Adding Future docs for Java API

akka-docs/java/code/akka/docs/future/FutureDocTestBase.java

@@ -4,6 +4,9 @@
 package akka.docs.future;
 
 //#imports1
+import akka.dispatch.Promise;
+import akka.japi.Procedure;
+import akka.japi.Procedure2;
 import akka.util.Timeout;
 import akka.dispatch.Await;
 import akka.dispatch.Future;
@@ -196,17 +199,19 @@ public class FutureDocTestBase {
     Iterable<Future<Integer>> listOfFutureInts = source;
 
     // now we have a Future[Iterable[Integer]]
-    Future<Iterable<Integer>> futureListOfInts = sequence(listOfFutureInts, system.dispatcher());
+    Future<Iterable<Integer>> futureListOfInts =
+            sequence(listOfFutureInts, system.dispatcher());
 
     // Find the sum of the odd numbers
-    Future<Long> futureSum = futureListOfInts.map(new Function<Iterable<Integer>, Long>() {
+    Future<Long> futureSum = futureListOfInts.map(
-      public Long apply(Iterable<Integer> ints) {
+      new Function<Iterable<Integer>, Long>() {
-        long sum = 0;
+          public Long apply(Iterable<Integer> ints) {
-        for (Integer i : ints)
+            long sum = 0;
-          sum += i;
+            for (Integer i : ints)
-        return sum;
+              sum += i;
-      }
+            return sum;
-    });
+          }
+      });
 
     long result = Await.result(futureSum, Duration.create(1, SECONDS));
     //#sequence
@@ -219,18 +224,20 @@ public class FutureDocTestBase {
     //Just a sequence of Strings
     Iterable<String> listStrings = Arrays.asList("a", "b", "c");
 
-    Future<Iterable<String>> futureResult = traverse(listStrings, new Function<String, Future<String>>() {
+    Future<Iterable<String>> futureResult = traverse(listStrings,
-      public Future<String> apply(final String r) {
+            new Function<String, Future<String>>() {
-        return future(new Callable<String>() {
+              public Future<String> apply(final String r) {
-          public String call() {
+                return future(new Callable<String>() {
-            return r.toUpperCase();
+                  public String call() {
-          }
+                    return r.toUpperCase();
-        }, system.dispatcher());
+                  }
-      }
+                }, system.dispatcher());
-    }, system.dispatcher());
+              }
+            }, system.dispatcher());
 
     //Returns the sequence of strings as upper case
-    Iterable<String> result = Await.result(futureResult, Duration.create(1, SECONDS));
+    Iterable<String> result =
+      Await.result(futureResult, Duration.create(1, SECONDS));
     assertEquals(Arrays.asList("A", "B", "C"), result);
     //#traverse
   }
@@ -246,11 +253,12 @@ public class FutureDocTestBase {
     Iterable<Future<String>> futures = source;
 
     //Start value is the empty string
-    Future<String> resultFuture = fold("", futures, new Function2<String, String, String>() {
+    Future<String> resultFuture = fold("", futures,
-      public String apply(String r, String t) {
+      new Function2<String, String, String>() {
-        return r + t; //Just concatenate
+          public String apply(String r, String t) {
-      }
+            return r + t; //Just concatenate
-    }, system.dispatcher());
+          }
+        }, system.dispatcher());
     String result = Await.result(resultFuture, Duration.create(1, SECONDS));
     //#fold
 
@@ -267,11 +275,12 @@ public class FutureDocTestBase {
     //A sequence of Futures, in this case Strings
     Iterable<Future<String>> futures = source;
 
-    Future<Object> resultFuture = reduce(futures, new Function2<Object, String, Object>() {
+    Future<Object> resultFuture = reduce(futures,
-      public Object apply(Object r, String t) {
+      new Function2<Object, String, Object>() {
-        return r + t; //Just concatenate
+          public Object apply(Object r, String t) {
-      }
+            return r + t; //Just concatenate
-    }, system.dispatcher());
+          }
+        }, system.dispatcher());
 
     Object result = Await.result(resultFuture, Duration.create(1, SECONDS));
     //#reduce
@@ -279,6 +288,116 @@ public class FutureDocTestBase {
     assertEquals("ab", result);
   }
 
+  @Test public void useSuccessfulAndFailed() {
+    //#successful
+    Future<String> future = Futures.successful("Yay!", system.dispatcher());
+    //#successful
+    //#failed
+    Future<String> otherFuture =
+            Futures.failed(new IllegalArgumentException("Bang!"), system.dispatcher());
+    //#failed
+    Object result = Await.result(future, Duration.create(1, SECONDS));
+    assertEquals("Yay!",result);
+    Throwable result2 = Await.result(otherFuture.failed(), Duration.create(1, SECONDS));
+    assertEquals("Bang!",result2.getMessage());
+  }
+
+  @Test public void useFilter() {
+       //#filter
+    Future<Integer> future1 = Futures.successful(4, system.dispatcher());
+    Future<Integer> successfulFilter =
+      future1.filter(new Function<Integer, Boolean>() {
+        public Boolean apply(Integer i) { return i % 2 == 0; }
+      });
+
+    Future<Integer> failedFilter =
+      future1.filter(new Function<Integer, Boolean>() {
+        public Boolean apply(Integer i) { return i % 2 != 0; }
+      });
+    //When filter fails, the returned Future will be failed with a scala.MatchError
+    //#filter
+  }
+
+  @Test public void useOnSuccessOnFailureAndOnComplete() {
+      {
+      Future<String> future = Futures.successful("foo", system.dispatcher());
+      //#onSuccess
+      future.onSuccess(new Procedure<String>() {
+          public void apply(String result) {
+              if ("bar" == result) {
+                  //Do something if it resulted in "bar"
+              } else {
+                  //Do something if it was some other String
+              }
+          }
+      });
+      //#onSuccess
+      }
+      {
+        Future<String> future =
+                Futures.failed(new IllegalStateException("OHNOES"), system.dispatcher());
+        //#onFailure
+      future.onFailure( new Procedure<Throwable>() {
+        public void apply(Throwable failure) {
+            if (failure instanceof IllegalStateException) {
+                //Do something if it was this particular failure
+            } else {
+                //Do something if it was some other failure
+            }
+        }
+      });
+      //#onFailure
+      }
+      {
+        Future<String> future = Futures.successful("foo", system.dispatcher());
+        //#onComplete
+        future.onComplete(new Procedure2<Throwable, String>() {
+           public void apply(Throwable failure, String result) {
+               if (failure != null) {
+                   //We got a failure, handle it here
+               } else {
+                   // We got a result, do something with it
+               }
+           }
+        });
+        //#onComplete
+      }
+  }
+
+  @Test public void useOrAndZip(){
+    {
+    //#zip
+    Future<String> future1 = Futures.successful("foo", system.dispatcher());
+    Future<String> future2 = Futures.successful("bar", system.dispatcher());
+    Future<String> future3 =
+      future1.zip(future2).map(new Function<scala.Tuple2<String,String>, String>() {
+        public String apply(scala.Tuple2<String,String> zipped) {
+            return zipped._1() + " " + zipped._2();
+        }
+    });
+
+    String result = Await.result(future3,  Duration.create(1, SECONDS));
+    assertEquals("foo bar", result);
+    //#zip
+    }
+
+    {
+        //#or
+        Future<String> future1 =
+                Futures.failed(new IllegalStateException("OHNOES1"), system.dispatcher());
+        Future<String> future2 =
+                Futures.failed(new IllegalStateException("OHNOES2"), system.dispatcher());
+        Future<String> future3 =
+                Futures.successful("bar", system.dispatcher());
+        Future<String> future4 =
+                future1.or(future2).or(future3); // Will have "bar" in this case
+        String result = Await.result(future4,  Duration.create(1, SECONDS));
+        assertEquals("bar", result);
+        //#or
+    }
+
+  }
+
   public static class MyActor extends UntypedActor {
     public void onReceive(Object message) {
       if (message instanceof String) {

akka-docs/java/futures.rst

@@ -10,86 +10,138 @@ Futures (Java)
 Introduction
 ------------
 
-In Akka, a `Future <http://en.wikipedia.org/wiki/Futures_and_promises>`_ is a data structure used to retrieve the result of some concurrent operation. This operation is usually performed by an ``Actor`` or by the ``Dispatcher`` directly. This result can be accessed synchronously (blocking) or asynchronously (non-blocking).
+In Akka, a `Future <http://en.wikipedia.org/wiki/Futures_and_promises>`_ is a data structure used
+to retrieve the result of some concurrent operation. This operation is usually performed by an ``Actor`` or
+by the ``Dispatcher`` directly. This result can be accessed synchronously (blocking) or asynchronously (non-blocking).
 
 Use with Actors
 ---------------
 
-There are generally two ways of getting a reply from an ``UntypedActor``: the first is by a sent message (``actorRef.tell(msg)``), which only works if the original sender was an ``UntypedActor``) and the second is through a ``Future``.
+There are generally two ways of getting a reply from an ``UntypedActor``: the first is by a sent message (``actorRef.tell(msg)``),
+which only works if the original sender was an ``UntypedActor``) and the second is through a ``Future``.
 
-Using the ``ActorRef``\'s ``ask`` method to send a message will return a Future. To wait for and retrieve the actual result the simplest method is:
+Using the ``ActorRef``\'s ``ask`` method to send a message will return a Future.
+To wait for and retrieve the actual result the simplest method is:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports1,ask-blocking
 
-This will cause the current thread to block and wait for the ``UntypedActor`` to 'complete' the ``Future`` with it's reply. Blocking is discouraged though as it can cause performance problem.
+This will cause the current thread to block and wait for the ``UntypedActor`` to 'complete' the ``Future`` with it's reply.
-The blocking operations are located in ``Await.result`` and ``Await.ready`` to make it easy to spot where blocking occurs. Alternatives to blocking are discussed further within this documentation.
+Blocking is discouraged though as it can cause performance problem.
-Also note that the ``Future`` returned by an ``UntypedActor`` is a ``Future<Object>`` since an ``UntypedActor`` is dynamic. That is why the cast to ``String`` is used in the above sample.
+The blocking operations are located in ``Await.result`` and ``Await.ready`` to make it easy to spot where blocking occurs.
+Alternatives to blocking are discussed further within this documentation.
+Also note that the ``Future`` returned by an ``UntypedActor`` is a ``Future<Object>`` since an ``UntypedActor`` is dynamic.
+That is why the cast to ``String`` is used in the above sample.
 
 Use Directly
 ------------
 
-A common use case within Akka is to have some computation performed concurrently without needing the extra utility of an ``UntypedActor``. If you find yourself creating a pool of ``UntypedActor``\s for the sole reason of performing a calculation in parallel, there is an easier (and faster) way:
+A common use case within Akka is to have some computation performed concurrently without needing
+the extra utility of an ``UntypedActor``. If you find yourself creating a pool of ``UntypedActor``\s for the sole reason
+of performing a calculation in parallel, there is an easier (and faster) way:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports2,future-eval
 
-In the above code the block passed to ``future`` will be executed by the default ``Dispatcher``, with the return value of the block used to complete the ``Future`` (in this case, the result would be the string: "HelloWorld"). Unlike a ``Future`` that is returned from an ``UntypedActor``, this ``Future`` is properly typed, and we also avoid the overhead of managing an ``UntypedActor``.
+In the above code the block passed to ``future`` will be executed by the default ``Dispatcher``,
+with the return value of the block used to complete the ``Future`` (in this case, the result would be the string: "HelloWorld").
+Unlike a ``Future`` that is returned from an ``UntypedActor``, this ``Future`` is properly typed,
+and we also avoid the overhead of managing an ``UntypedActor``.
+
+You can also create already completed Futures using the ``Futures`` class, which can be either successes:
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: successful
+
+Or failures:
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: failed
 
 Functional Futures
 ------------------
 
-Akka's ``Future`` has several monadic methods that are very similar to the ones used by ``Scala``'s collections. These allow you to create 'pipelines' or 'streams' that the result will travel through.
+Akka's ``Future`` has several monadic methods that are very similar to the ones used by ``Scala``'s collections.
+These allow you to create 'pipelines' or 'streams' that the result will travel through.
 
 Future is a Monad
 ^^^^^^^^^^^^^^^^^
 
-The first method for working with ``Future`` functionally is ``map``. This method takes a ``Function`` which performs some operation on the result of the ``Future``, and returning a new result. The return value of the ``map`` method is another ``Future`` that will contain the new result:
+The first method for working with ``Future`` functionally is ``map``. This method takes a ``Function`` which performs
+some operation on the result of the ``Future``, and returning a new result.
+The return value of the ``map`` method is another ``Future`` that will contain the new result:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports2,map
 
-In this example we are joining two strings together within a Future. Instead of waiting for f1 to complete, we apply our function that calculates the length of the string using the ``map`` method. Now we have a second Future, f2, that will eventually contain an ``Integer``. When our original ``Future``, f1, completes, it will also apply our function and complete the second Future with it's result. When we finally ``get`` the result, it will contain the number 10. Our original Future still contains the string "HelloWorld" and is unaffected by the ``map``.
+In this example we are joining two strings together within a Future. Instead of waiting for f1 to complete,
+we apply our function that calculates the length of the string using the ``map`` method.
+Now we have a second Future, f2, that will eventually contain an ``Integer``.
+When our original ``Future``, f1, completes, it will also apply our function and complete the second Future
+with its result. When we finally ``get`` the result, it will contain the number 10.
+Our original Future still contains the string "HelloWorld" and is unaffected by the ``map``.
 
-Something to note when using these methods: if the ``Future`` is still being processed when one of these methods are called, it will be the completing thread that actually does the work. If the ``Future`` is already complete though, it will be run in our current thread. For example:
+Something to note when using these methods: if the ``Future`` is still being processed when one of these methods are called,
+it will be the completing thread that actually does the work.
+If the ``Future`` is already complete though, it will be run in our current thread. For example:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: map2
 
-The original ``Future`` will take at least 0.1 second to execute now, which means it is still being processed at the time we call ``map``. The function we provide gets stored within the ``Future`` and later executed automatically by the dispatcher when the result is ready.
+The original ``Future`` will take at least 0.1 second to execute now, which means it is still being processed at
+the time we call ``map``. The function we provide gets stored within the ``Future`` and later executed automatically
+by the dispatcher when the result is ready.
 
 If we do the opposite:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: map3
 
-Our little string has been processed long before our 0.1 second sleep has finished. Because of this, the dispatcher has moved onto other messages that need processing and can no longer calculate the length of the string for us, instead it gets calculated in the current thread just as if we weren't using a ``Future``.
+Our little string has been processed long before our 0.1 second sleep has finished. Because of this,
+the dispatcher has moved onto other messages that need processing and can no longer calculate
+the length of the string for us, instead it gets calculated in the current thread just as if we weren't using a ``Future``.
 
-Normally this works quite well as it means there is very little overhead to running a quick function. If there is a possibility of the function taking a non-trivial amount of time to process it might be better to have this done concurrently, and for that we use ``flatMap``:
+Normally this works quite well as it means there is very little overhead to running a quick function.
+If there is a possibility of the function taking a non-trivial amount of time to process it might be better
+to have this done concurrently, and for that we use ``flatMap``:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: flat-map
 
-Now our second Future is executed concurrently as well. This technique can also be used to combine the results of several Futures into a single calculation, which will be better explained in the following sections.
+Now our second Future is executed concurrently as well. This technique can also be used to combine the results
+of several Futures into a single calculation, which will be better explained in the following sections.
+
+If you need to do conditional propagation, you can use ``filter``:
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: filter
 
 Composing Futures
 ^^^^^^^^^^^^^^^^^
 
-It is very often desirable to be able to combine different Futures with eachother, below are some examples on how that can be done in a non-blocking fashion.
+It is very often desirable to be able to combine different Futures with each other,
+below are some examples on how that can be done in a non-blocking fashion.
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports3,sequence
 
-To better explain what happened in the example, ``Future.sequence`` is taking the ``Iterable<Future<Integer>>`` and turning it into a ``Future<Iterable<Integer>>``. We can then use ``map`` to work with the ``Iterable<Integer>`` directly, and we aggregate the sum of the ``Iterable``.
+To better explain what happened in the example, ``Future.sequence`` is taking the ``Iterable<Future<Integer>>``
+and turning it into a ``Future<Iterable<Integer>>``. We can then use ``map`` to work with the ``Iterable<Integer>`` directly,
+and we aggregate the sum of the ``Iterable``.
 
-The ``traverse`` method is similar to ``sequence``, but it takes a sequence of ``A``s and applies a function from ``A`` to ``Future<B>`` and returns a ``Future<Iterable<B>>``, enabling parallel ``map`` over the sequence, if you use ``Futures.future`` to create the ``Future``.
+The ``traverse`` method is similar to ``sequence``, but it takes a sequence of ``A``s and applies a function from ``A`` to ``Future<B>``
+and returns a ``Future<Iterable<B>>``, enabling parallel ``map`` over the sequence, if you use ``Futures.future`` to create the ``Future``.
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports4,traverse
 
 It's as simple as that!
 
-Then there's a method that's called ``fold`` that takes a start-value, a sequence of ``Future``:s and a function from the type of the start-value, a timeout, and the type of the futures and returns something with the same type as the start-value, and then applies the function to all elements in the sequence of futures, non-blockingly, the execution will run on the Thread of the last completing Future in the sequence.
+Then there's a method that's called ``fold`` that takes a start-value,
+a sequence of ``Future``:s and a function from the type of the start-value, a timeout,
+and the type of the futures and returns something with the same type as the start-value,
+and then applies the function to all elements in the sequence of futures, non-blockingly,
+the execution will be started when the last of the Futures is completed.
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports5,fold
@@ -97,16 +149,52 @@ Then there's a method that's called ``fold`` that takes a start-value, a sequenc
 That's all it takes!
 
 
-If the sequence passed to ``fold`` is empty, it will return the start-value, in the case above, that will be empty String. In some cases you don't have a start-value and you're able to use the value of the first completing Future in the sequence as the start-value, you can use ``reduce``, it works like this:
+If the sequence passed to ``fold`` is empty, it will return the start-value, in the case above, that will be empty String.
+In some cases you don't have a start-value and you're able to use the value of the first completing Future
+in the sequence as the start-value, you can use ``reduce``, it works like this:
 
 .. includecode:: code/akka/docs/future/FutureDocTestBase.java
    :include: imports6,reduce
 
-Same as with ``fold``, the execution will be done by the Thread that completes the last of the Futures, you can also parallize it by chunking your futures into sub-sequences and reduce them, and then reduce the reduced results again.
+Same as with ``fold``, the execution will be started when the last of the Futures is completed, you can also parallelize
+it by chunking your futures into sub-sequences and reduce them, and then reduce the reduced results again.
 
 This is just a sample of what can be done.
 
+Callbacks
+---------
+
+Sometimes you just want to listen to a ``Future`` being completed, and react to that not by creating a new Future, but by side-effecting.
+For this Akka supports ``onComplete``, ``onSuccess`` and ``onFailure``, of which the latter two are specializations of the first.
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: onSuccess
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: onFailure
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: onComplete
+
+Auxiliary methods
+-----------------
+
+``Future`` ``or`` combines 2 Futures into a new ``Future``, and will hold the successful value of the second ``Future`
+if the first ``Future`` fails.
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: or
+
+You can also combine two Futures into a new ``Future`` that will hold a tuple of the two Futures successful results,
+using the ``zip`` operation.
+
+.. includecode:: code/akka/docs/future/FutureDocTestBase.java
+   :include: zip
+
 Exceptions
 ----------
 
-Since the result of a ``Future`` is created concurrently to the rest of the program, exceptions must be handled differently. It doesn't matter if an ``UntypedActor`` or the dispatcher is completing the ``Future``, if an ``Exception`` is caught the ``Future`` will contain it instead of a valid result. If a ``Future`` does contain an ``Exception``, calling ``Await.result`` will cause it to be thrown again so it can be handled properly.
+Since the result of a ``Future`` is created concurrently to the rest of the program, exceptions must be handled differently.
+It doesn't matter if an ``UntypedActor`` or the dispatcher is completing the ``Future``, if an ``Exception`` is caught
+the ``Future`` will contain it instead of a valid result. If a ``Future`` does contain an ``Exception``,
+calling ``Await.result`` will cause it to be thrown again so it can be handled properly.