Merge pull request #638 from akka/wip-2410-doc-pattern-after-patriknw

DOC: Describe pattern.after, see #2410

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

@@ -48,6 +48,11 @@ import scala.concurrent.ExecutionContext$;
 
 //#imports7
 
+//#imports8
+import static akka.pattern.Patterns.after;
+
+//#imports8
+
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
@@ -508,6 +513,24 @@ public class FutureDocTestBase {
 
   }
 
+  @Test(expected = IllegalStateException.class)
+  public void useAfter() throws Exception {
+    //#after
+    final ExecutionContext ec = system.dispatcher();
+    Future<String> failExc = Futures.failed(new IllegalStateException("OHNOES1"));
+    Future<String> delayed = Patterns.after(Duration.parse("500 millis"),
+      system.scheduler(), ec,  failExc);
+    Future<String> future = future(new Callable<String>() {
+      public String call() throws InterruptedException {
+        Thread.sleep(1000);
+        return "foo";
+      }
+    }, ec);
+    Future<String> result = future.either(delayed);
+    //#after
+    Await.result(result, Duration.create(2, SECONDS));
+  }
+
   public static class MyActor extends UntypedActor {
     public void onReceive(Object message) {
       if (message instanceof String) {

akka-docs/java/futures.rst

@@ -235,3 +235,10 @@ and is use like this:
 .. includecode:: code/docs/future/FutureDocTestBase.java
    :include: try-recover
 
+After
+-----
+
+``akka.pattern.Patterns.after`` makes it easy to complete a ``Future`` with a value or exception after a timeout.
+
+.. includecode:: code/docs/future/FutureDocTestBase.java
+   :include: imports8,after

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

@@ -377,4 +377,16 @@ class FutureDocSpec extends AkkaSpec {
     intercept[IllegalArgumentException] { Await.result(otherFuture, 1 second) }
   }
 
+  "demonstrate usage of pattern.after" in {
+    //#after
+    import akka.pattern.after
+
+    val delayed = after(200 millis, using = system.scheduler)(Future.failed(
+      new IllegalStateException("OHNOES")))
+    val future = Future { Thread.sleep(1000); "foo" }
+    val result = future either delayed
+    //#after
+    intercept[IllegalStateException] { Await.result(result, 2 second) }
+  }
+
 }

akka-docs/scala/futures.rst

@@ -261,3 +261,10 @@ and is use like this:
 .. includecode:: code/docs/future/FutureDocSpec.scala
    :include: try-recover
 
+After
+-----
+
+``akka.pattern.after`` makes it easy to complete a ``Future`` with a value or exception after a timeout.
+
+.. includecode:: code/docs/future/FutureDocSpec.scala
+   :include: after