+doc: Added materialized value handling section for Java

akka-docs-dev/rst/java/stream-flows-and-basics.rst

@@ -196,6 +196,16 @@ which will be running on the thread pools they have been configured to run on -
    Reusing *instances* of linear computation stages (Source, Sink, Flow) inside FlowGraphs is legal,
    yet will materialize that stage multiple times.
 
+Combining materialized values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since every processing stage in Akka Streams can provide a materialized value after being materialized, it is necessary
+to somehow express how these values should be composed to a final value when we plug these stages together. For this,
+many combinator methods have variants that take an additional argument, a function, that will be used to combine the
+resulting values. Some examples of using these combiners are illustrated in the example below.
+
+.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowDocSpec.scala#flow-mat-combine
+
 
 Stream ordering
 ===============

akka-stream/src/main/scala/akka/stream/javadsl/Source.scala

@@ -12,7 +12,7 @@ import org.reactivestreams.Publisher
 import org.reactivestreams.Subscriber
 import scala.annotation.unchecked.uncheckedVariance
 import scala.collection.JavaConverters._
-import scala.concurrent.Future
+import scala.concurrent.{Promise, Future}
 import scala.concurrent.duration.FiniteDuration
 import scala.language.higherKinds
 import scala.language.implicitConversions
@@ -46,8 +46,8 @@ object Source {
    * be used to externally trigger completion, which the source then signalls
    * to its downstream.
    */
-  def lazyEmpty[T]() =
-    new Source(scaladsl.Source.lazyEmpty())
+  def lazyEmpty[T](): Source[T, Promise[Unit]] =
+    new Source[T, Promise[Unit]](scaladsl.Source.lazyEmpty())
 
   /**
    * Helper to create [[Source]] from `Publisher`.