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,25 @@ 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 = Futures.firstCompletedOf(
+      Arrays.asList(future, delayed), ec);
+    //#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