add section about Java 8 APIs #19655

This is not a complete documentation rewrite to put CompletionStage in
everywhere, that is some that is impossible to slot in right now.

fixes #19655

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

@@ -49,7 +49,7 @@ Just like in the case of the super-pool flow described above the request must ha
 Using the Future-Based API in Actors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 When using the ``CompletionStage`` 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
+with the futures completion. For example you should not access the Actors state from within the CompletionStage'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:
 

akka-docs/rst/java/http/client-side/websocket-support.rst

@@ -60,7 +60,7 @@ The websocket request may also include additional headers, like in this example,
 
 webSocketClientFlow
 -------------------
-``webSocketClientFlow`` takes a request, and returns a ``Flow<Message, Message, Future<WebSocketUpgradeResponse>>``.
+``webSocketClientFlow`` takes a request, and returns a ``Flow<Message, Message, CompletionStage<WebSocketUpgradeResponse>>``.
 
 The future that is materialized from the flow will succeed when the WebSocket connection has been established or
 the server returned a regular HTTP response, or fail if the connection fails with an exception.