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/futures.rst

@@ -11,6 +11,8 @@ used to retrieve the result of some concurrent operation. This result can be acc
 or asynchronously (non-blocking). To be able to use this from Java, Akka provides a java friendly interface
 in ``akka.dispatch.Futures``.
 
+See also :ref:`actor-java-lambda` for Java compatibility.
+
 Execution Contexts
 ------------------
 

akka-docs/rst/java/howto.rst

@@ -57,7 +57,7 @@ This method starts a temporary actor to forward the message and collect the resu
 In case of errors within the asked actor the default supervision handling will take over.
 The caller of Patterns.ask() will *not* be notified.
 
-If that caller is interested in such an exception, he must make sure that the asked actor replies with Status.Failure(Throwable).
+If that caller is interested in such an exception, they must make sure that the asked actor replies with Status.Failure(Throwable).
 Behind the asked actor a complex actor hierarchy might be spawned to accomplish asynchronous work.
 Then supervision is the established way to control error handling.
 
@@ -65,7 +65,8 @@ Unfortunately the asked actor must know about supervision and must catch the exc
 Such an actor is unlikely to be reused in a different actor hierarchy and contains crippled try/catch blocks.
 
 This pattern provides a way to encapsulate supervision and error propagation to the temporary actor.
-Finally the promise returned by Patterns.ask() is fulfilled as a failure, including the exception.
+Finally the promise returned by Patterns.ask() is fulfilled as a failure, including the exception
+(see also :ref:`actor-java-lambda` for Java compatibility).
 
 Let's have a look at the example code:
 

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.

akka-docs/rst/java/lambda-actors.rst

@@ -473,9 +473,10 @@ of that reply is guaranteed, it still is a normal message.
 .. includecode:: code/docs/actorlambda/ActorDocTest.java#identify
 
 You can also acquire an :class:`ActorRef` for an :class:`ActorSelection` with
-the ``resolveOne`` method of the :class:`ActorSelection`. It returns a ``Future``
-of the matching :class:`ActorRef` if such an actor exists. It is completed with
-failure [[akka.actor.ActorNotFound]] if no such actor exists or the identification
+the ``resolveOne`` method of the :class:`ActorSelection`. It returns a
+``Future`` of the matching :class:`ActorRef` if such an actor exists (see also
+:ref:`actor-java-lambda` for Java compatibility). It is completed with failure
+[[akka.actor.ActorNotFound]] if no such actor exists or the identification
 didn't complete within the supplied `timeout`.
 
 Remote actor addresses may also be looked up, if :ref:`remoting <remoting-java>` is enabled:

akka-docs/rst/java/lambda-index-actors.rst

@@ -1,6 +1,28 @@
+.. _actor-java-lambda:
+
 Actors (Java with Lambda Support)
 =================================
 
+Starting with Akka 2.4.2 we have begun to introduce Java 8 types (most
+prominently ``java.util.concurrent.CompletionStage`` and
+``java.util.Optional``) where that was possible without breaking binary or
+source compatibility. Where this was not possible (for example in the return
+type of ``ActorSystem.terminate()``) please refer to the
+``scala-java8-compat`` library that allows easy conversion between the Scala
+and Java counterparts. The artifact can be included in Maven builds using::
+
+    <dependency>
+      <groupId>org.scala-lang.modules</groupId>
+      <artifactId>scala-java8-compat_2.11</artifactId>
+      <version>0.7.0</version>
+    </dependency>
+
+We will only be able to seamlessly integrate all functional interfaces once
+we can rely on Scala 2.12 to provide full interoperability—this will mean that
+Scala users can directly implement Java Functional Interfaces using lambda syntax
+as well as that Java users can directly implement Scala functions using lambda
+syntax.
+
 .. toctree::
    :maxdepth: 2
 

akka-docs/rst/java/lambda-persistence.rst

@@ -327,15 +327,13 @@ command, i.e. ``onPersistRejected`` is called with an exception (typically ``Uns
 Batch writes
 ------------
 
-In order to optimize throughput, a persistent actor internally batches events to be stored under high load before
-writing them to the journal (as a single batch). The batch size dynamically grows from 1 under low and moderate loads
-to a configurable maximum size (default is ``200``) under high load. When using ``persistAsync`` this increases
-the maximum throughput dramatically.
-
-.. includecode:: ../scala/code/docs/persistence/PersistencePluginDocSpec.scala#max-message-batch-size
-
-A new batch write is triggered by a persistent actor as soon as a batch reaches the maximum size or if the journal completed
-writing the previous batch. Batch writes are never timer-based which keeps latencies at a minimum.
+In order to optimize throughput when using ``persistAsync``, a persistent actor
+internally batches events to be stored under high load before writing them to
+the journal (as a single batch). The batch size is dynamically determined by
+how many events are emitted during the time of a journal round-trip: after
+sending a batch to the journal no further batch can be sent before confirmation
+has been received that the previous batch has been written. Batch writes are never
+timer-based which keeps latencies at a minimum.
 
 Message deletion
 ----------------