Merge pull request #17210 from ktoso/wip-concat-docs-ktoso

Document mapConcat's Seq should not contain nulls

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

@@ -104,6 +104,11 @@ There are various ways to wire up different parts of a stream, the following exa
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowDocTest.java#flow-connecting
 
+Illegal stream elements
+^^^^^^^^^^^^^^^^^^^^^^^
+In accordance to the Reactive Streams specification (`Rule 2.13 <https://github.com/reactive-streams/reactive-streams-jvm#2.13>`_)
+Akka Streams do not allow ``null`` to be passed through the stream as an element. In case you want to model the concept
+of absence of a value we recommend using ``akka.japi.Option`` (for Java 6 and 7) or ``java.util.Optional`` which is available since Java 8.
 
 .. _back-pressure-explained-java:
 

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

@@ -108,6 +108,11 @@ There are various ways to wire up different parts of a stream, the following exa
 
 .. includecode:: code/docs/stream/FlowDocSpec.scala#flow-connecting
 
+Illegal stream elements
+^^^^^^^^^^^^^^^^^^^^^^^
+In accordance to the Reactive Streams specification (`Rule 2.13 <https://github.com/reactive-streams/reactive-streams-jvm#2.13>`_)
+Akka Streams do not allow ``null`` to be passed through the stream as an element. In case you want to model the concept
+of absence of a value we recommend using ``scala.Option`` or ``scala.util.Either``.
 
 .. _back-pressure-explained-scala:
 

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

@@ -154,6 +154,9 @@ class Flow[-In, +Out, +Mat](delegate: scaladsl.Flow[In, Out, Mat]) extends Graph
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned list MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: japi.Function[Out, java.util.List[T]]): javadsl.Flow[In, T, Mat] =
     new Flow(delegate.mapConcat(elem ⇒ Util.immutableSeq(f.apply(elem))))

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

@@ -292,6 +292,9 @@ class Source[+Out, +Mat](delegate: scaladsl.Source[Out, Mat]) extends Graph[Sour
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned list MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: japi.Function[Out, java.util.List[T]]): javadsl.Source[T, Mat] =
     new Source(delegate.mapConcat(elem ⇒ Util.immutableSeq(f.apply(elem))))

akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala

@@ -344,6 +344,9 @@ trait FlowOps[+Out, +Mat] {
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned sequence MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: Out ⇒ immutable.Seq[T]): Repr[T, Mat] = andThen(MapConcat(f.asInstanceOf[Any ⇒ immutable.Seq[Any]]))