+doc,htc #18610 document using singleRequest in Actors

akka-docs-dev/rst/java/code/docs/http/javadsl/HttpClientExampleDocTest.java

@@ -4,10 +4,14 @@
 
 package docs.http.javadsl;
 
+import akka.actor.AbstractActor;
 import akka.actor.ActorSystem;
 import akka.http.javadsl.HostConnectionPool;
 import akka.japi.Pair;
 
+import akka.japi.pf.ReceiveBuilder;
+import akka.stream.Materializer;
+import scala.concurrent.ExecutionContextExecutor;
 import scala.concurrent.Future;
 import akka.stream.ActorMaterializer;
 import akka.stream.javadsl.*;
@@ -16,6 +20,8 @@ import akka.http.javadsl.model.*;
 import akka.http.javadsl.Http;
 import scala.util.Try;
 
+import static akka.pattern.Patterns.*;
+
 @SuppressWarnings("unused")
 public class HttpClientExampleDocTest {
 
@@ -62,11 +68,32 @@ public class HttpClientExampleDocTest {
   public void testSingleRequestExample() {
     //#single-request-example
     final ActorSystem system = ActorSystem.create();
-    final ActorMaterializer materializer = ActorMaterializer.create(system);
+    final Materializer materializer = ActorMaterializer.create(system);
 
     final Future<HttpResponse> responseFuture =
       Http.get(system)
           .singleRequest(HttpRequest.create("http://akka.io"), materializer);
     //#single-request-example
   }
-}
+
+  static
+      //#single-request-in-actor-example
+    class Myself extends AbstractActor {
+      final Http http = Http.get(context().system());
+      final ExecutionContextExecutor dispatcher = context().dispatcher();
+      final Materializer materializer = ActorMaterializer.create(context());
+
+      public Myself() {
+        receive(ReceiveBuilder
+         .match(String.class, url -> {
+           pipe(fetch (url), dispatcher).to(self());
+         }).build());
+      }
+
+      Future<HttpResponse> fetch(String url) {
+        return http.singleRequest(HttpRequest.create(url), materializer);
+      }
+    }
+    //#single-request-in-actor-example
+
+}

akka-docs-dev/rst/java/http/client-side/request-level.rst

@@ -44,8 +44,13 @@ request's effective URI.
 Just like in the case of the super-pool flow described above the request must have either an absolute URI or a valid
 ``Host`` header, otherwise the returned future will be completed with an error.
 
+.. includecode:: ../../code/docs/http/javadsl/HttpClientExampleDocTest.java#single-request-example
 
-Example
--------
+Using the Future-Based API in Actors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When using the ``Future`` based API from inside an ``Actor``, all the usual caveats apply to how one should deal
+with the futures completion. For example you should not access the Actors state from within the Future's callbacks
+(such as ``map``, ``onComplete``, ...) and instead you should use the ``pipe`` pattern to pipe the result back
+to the Actor as a message:
 
-.. includecode:: ../../code/docs/http/javadsl/HttpClientExampleDocTest.java#single-request-example
+.. includecode:: ../../code/docs/http/javadsl/HttpClientExampleDocTest.java#single-request-in-actor-example