add Futures.promise to the docs

akka-docs/rst/java/code/docs/future/FutureDocTest.java

@@ -8,6 +8,7 @@ import akka.dispatch.*;
 import scala.concurrent.ExecutionContext;
 import scala.concurrent.Future;
 import scala.concurrent.Await;
+import scala.concurrent.Promise;
 import akka.util.Timeout;
 //#imports1
 
@@ -340,7 +341,7 @@ public class FutureDocTest {
   }
 
   @Test
-  public void useSuccessfulAndFailed() throws Exception {
+  public void useSuccessfulAndFailedAndPromise() throws Exception {
     final ExecutionContext ec = system.dispatcher();
     //#successful
     Future<String> future = Futures.successful("Yay!");
@@ -349,11 +350,18 @@ public class FutureDocTest {
     Future<String> otherFuture = Futures.failed(
       new IllegalArgumentException("Bang!"));
     //#failed
+    //#promise
+    Promise<String> promise = Futures.promise();
+    Future<String> theFuture = promise.future();
+    promise.success("hello");
+    //#promise
     Object result = Await.result(future, Duration.create(5, SECONDS));
     assertEquals("Yay!", result);
     Throwable result2 = Await.result(otherFuture.failed(),
       Duration.create(5, SECONDS));
     assertEquals("Bang!", result2.getMessage());
+    String out = Await.result(theFuture, Duration.create(5, SECONDS));
+    assertEquals("hello", out);
   }
 
   @Test

akka-docs/rst/java/futures.rst

@@ -86,6 +86,10 @@ Or failures:
 .. includecode:: code/docs/future/FutureDocTest.java
    :include: failed
 
+It is also possible to create an empty ``Promise``, to be filled later, and obtain the corresponding ``Future``:
+
+.. includecode:: code/docs/future/FutureDocTestBase.java#promise
+
 For these examples ``PrintResult`` is defined as follows:
 
 .. includecode:: code/docs/future/FutureDocTest.java

akka-docs/rst/scala/code/docs/future/FutureDocSpec.scala

@@ -399,15 +399,21 @@ class FutureDocSpec extends AkkaSpec {
     }
   }
 
-  "demonstrate usage of Future.successful & Future.failed" in {
+  "demonstrate usage of Future.successful & Future.failed & Future.promise" in {
     //#successful
     val future = Future.successful("Yay!")
     //#successful
     //#failed
     val otherFuture = Future.failed[String](new IllegalArgumentException("Bang!"))
     //#failed
+    //#promise
+    val promise = Promise[String]()
+    val theFuture = promise.future
+    promise.success("hello")
+    //#promise
     Await.result(future, 3 seconds) must be("Yay!")
     intercept[IllegalArgumentException] { Await.result(otherFuture, 3 seconds) }
+    Await.result(theFuture, 3 seconds) must be("hello")
   }
 
   "demonstrate usage of pattern.after" in {

akka-docs/rst/scala/futures.rst

@@ -89,6 +89,11 @@ Or failures:
 .. includecode:: code/docs/future/FutureDocSpec.scala
    :include: failed
 
+It is also possible to create an empty ``Promise``, to be filled later, and obtain the corresponding ``Future``:
+
+.. includecode:: code/docs/future/FutureDocSpec.scala
+   :include: promise
+
 Functional Futures
 ------------------