Merge pull request #19750 from lolski/lolski-issue-19293-rebased

=str #19293 fix issues in Sink.seq + minor doc fixes + use Sink.seq

akka-docs/rst/java/code/docs/stream/FlowStagesDocTest.java

@@ -156,7 +156,7 @@ public class FlowStagesDocTest {
   @Test
   public void demonstrateVariousPushPullStages() throws Exception {
     final Sink<Integer, CompletionStage<List<Integer>>> sink =
-        Flow.of(Integer.class).grouped(10).toMat(Sink.head(), Keep.right());
+      Flow.of(Integer.class).limit(10).toMat(Sink.seq(), Keep.right());
 
     //#stage-chain
     final RunnableGraph<CompletionStage<List<Integer>>> runnable =

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeByteStrings.java

@@ -95,7 +95,7 @@ public class RecipeByteStrings extends RecipeTest {
           rawBytes.transform(() -> new Chunker(CHUNK_LIMIT));
         //#bytestring-chunker2
 
-        CompletionStage<List<ByteString>> chunksFuture = chunksStream.grouped(10).runWith(Sink.head(), mat);
+        CompletionStage<List<ByteString>> chunksFuture = chunksStream.limit(10).runWith(Sink.seq(), mat);
 
         List<ByteString> chunks = chunksFuture.toCompletableFuture().get(3, TimeUnit.SECONDS);
 
@@ -157,7 +157,7 @@ public class RecipeByteStrings extends RecipeTest {
           ByteString.fromArray(new byte[] { 4, 5, 6 }),
           ByteString.fromArray(new byte[] { 7, 8, 9, 10 })));
 
-        List<ByteString> got = bytes1.via(limiter).grouped(10).runWith(Sink.head(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
+        List<ByteString> got = bytes1.via(limiter).limit(10).runWith(Sink.seq(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
         ByteString acc = ByteString.empty();
         for (ByteString b : got) {
           acc = acc.concat(b);
@@ -166,7 +166,7 @@ public class RecipeByteStrings extends RecipeTest {
 
         boolean thrown = false;
         try {
-          bytes2.via(limiter).grouped(10).runWith(Sink.head(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
+          bytes2.via(limiter).limit(10).runWith(Sink.seq(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
         } catch (IllegalStateException ex) {
           thrown = true;
         }
@@ -190,7 +190,7 @@ public class RecipeByteStrings extends RecipeTest {
         Source<ByteString, NotUsed> compacted = rawBytes.map(bs -> bs.compact());
         //#compacting-bytestrings
 
-        List<ByteString> got = compacted.grouped(10).runWith(Sink.head(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
+        List<ByteString> got = compacted.limit(10).runWith(Sink.seq(), mat).toCompletableFuture().get(3, TimeUnit.SECONDS);
 
         for (ByteString byteString : got) {
           assertTrue(byteString.isCompact());

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeFlattenList.java

@@ -48,7 +48,7 @@ public class RecipeFlattenList extends RecipeTest {
         Source<Message, NotUsed> flattened = myData.mapConcat(i -> i);
         //#flattening-lists
 
-        List<Message> got = flattened.grouped(10).runWith(Sink.head(), mat).toCompletableFuture().get(1, TimeUnit.SECONDS);
+        List<Message> got = flattened.limit(10).runWith(Sink.seq(), mat).toCompletableFuture().get(1, TimeUnit.SECONDS);
         assertEquals(got.get(0), new Message("1"));
         assertEquals(got.get(1), new Message("2"));
         assertEquals(got.get(2), new Message("3"));

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeParseLines.java

@@ -50,8 +50,7 @@ public class RecipeParseLines extends RecipeTest {
       .via(Framing.delimiter(ByteString.fromString("\r\n"), 100, true))
       .map(b -> b.utf8String());
     //#parse-lines
-
-    lines.grouped(10).runWith(Sink.head(), mat).toCompletableFuture().get(1, TimeUnit.SECONDS);
+    lines.limit(10).runWith(Sink.seq(), mat).toCompletableFuture().get(1, TimeUnit.SECONDS);
   }
 
 }

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeSeq.java

@@ -0,0 +1,92 @@
+/**
+ *  Copyright (C) 2015-2016 Typesafe <http://typesafe.com/>
+ */
+package docs.stream.javadsl.cookbook;
+
+import akka.NotUsed;
+import akka.actor.ActorSystem;
+import akka.stream.ActorMaterializer;
+import akka.stream.Materializer;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+import akka.testkit.JavaTestKit;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import scala.concurrent.Await;
+import scala.concurrent.Future;
+import scala.concurrent.duration.FiniteDuration;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.TimeUnit;
+
+public class RecipeSeq extends RecipeTest {
+  static ActorSystem system;
+
+  @BeforeClass
+  public static void setup() {
+    system = ActorSystem.create("RecipeLoggingElements");
+  }
+
+  @AfterClass
+  public static void tearDown() {
+    JavaTestKit.shutdownActorSystem(system);
+    system = null;
+  }
+
+  final Materializer mat = ActorMaterializer.create(system);
+
+  @Test
+  public void drainSourceToList() throws Exception {
+    new JavaTestKit(system) {
+      {
+        //#draining-to-list-unsafe
+        final Source<String, NotUsed> myData = Source.from(Arrays.asList("1", "2", "3"));
+        final int MAX_ALLOWED_SIZE = 100;
+
+        final CompletionStage<List<String>> strings = myData.runWith(Sink.seq(), mat); // dangerous!
+        //#draining-to-list-unsafe
+
+        strings.toCompletableFuture().get(3, TimeUnit.SECONDS);
+      }
+    };
+  }
+
+  @Test
+  public void drainSourceToListWithLimit() throws Exception {
+    new JavaTestKit(system) {
+      {
+        //#draining-to-list-safe
+        final Source<String, NotUsed> myData = Source.from(Arrays.asList("1", "2", "3"));
+        final int MAX_ALLOWED_SIZE = 100;
+
+        // OK. Future will fail with a `StreamLimitReachedException`
+        // if the number of incoming elements is larger than max
+        final CompletionStage<List<String>> strings =
+          myData.limit(MAX_ALLOWED_SIZE).runWith(Sink.seq(), mat);
+        //#draining-to-list-safe
+
+        strings.toCompletableFuture().get(1, TimeUnit.SECONDS);
+      }
+    };
+  }
+
+  public void drainSourceToListWithTake() throws Exception {
+    new JavaTestKit(system) {
+      {
+        final Source<String, NotUsed> myData = Source.from(Arrays.asList("1", "2", "3"));
+        final int MAX_ALLOWED_SIZE = 100;
+
+        //#draining-to-list-safe
+        // OK. Collect up until max-th elements only, then cancel upstream
+        final CompletionStage<List<String>> strings =
+                myData.take(MAX_ALLOWED_SIZE).runWith(Sink.seq(), mat);
+        //#draining-to-list-safe
+
+        strings.toCompletableFuture().get(1, TimeUnit.SECONDS);
+      }
+    };
+  }
+}

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeToStrict.java

@@ -1,58 +0,0 @@
-/**
- *  Copyright (C) 2015-2016 Typesafe <http://typesafe.com/>
- */
-package docs.stream.javadsl.cookbook;
-
-import akka.NotUsed;
-import akka.actor.ActorSystem;
-import akka.stream.ActorMaterializer;
-import akka.stream.Materializer;
-import akka.stream.javadsl.Sink;
-import akka.stream.javadsl.Source;
-import akka.testkit.JavaTestKit;
-import org.junit.AfterClass;
-import org.junit.BeforeClass;
-import org.junit.Test;
-import scala.concurrent.Await;
-import scala.concurrent.Future;
-import scala.concurrent.duration.FiniteDuration;
-
-import java.util.Arrays;
-import java.util.List;
-import java.util.concurrent.CompletionStage;
-import java.util.concurrent.TimeUnit;
-
-public class RecipeToStrict extends RecipeTest {
-  static ActorSystem system;
-
-  @BeforeClass
-  public static void setup() {
-    system = ActorSystem.create("RecipeLoggingElements");
-  }
-
-  @AfterClass
-  public static void tearDown() {
-    JavaTestKit.shutdownActorSystem(system);
-    system = null;
-  }
-
-  final Materializer mat = ActorMaterializer.create(system);
-
-  @Test
-  public void workWithPrintln() throws Exception {
-    new JavaTestKit(system) {
-      {
-        final Source<String, NotUsed> myData = Source.from(Arrays.asList("1", "2", "3"));
-        final int MAX_ALLOWED_SIZE = 100;
-
-        //#draining-to-list
-        final CompletionStage<List<String>> strings = myData
-          .grouped(MAX_ALLOWED_SIZE).runWith(Sink.head(), mat);
-        //#draining-to-list
-
-        strings.toCompletableFuture().get(3, TimeUnit.SECONDS);
-      }
-    };
-  }
-
-}

akka-docs/rst/java/code/docs/stream/javadsl/cookbook/RecipeWorkerPool.java

@@ -73,7 +73,8 @@ public class RecipeWorkerPool extends RecipeTest {
         Source<Message, NotUsed> processedJobs = data.via(balancer);
         //#worker-pool2
 
-        CompletionStage<List<String>> future = processedJobs.map(m -> m.msg).grouped(10).runWith(Sink.head(), mat);
+        FiniteDuration timeout = FiniteDuration.create(200, TimeUnit.MILLISECONDS);
+        CompletionStage<List<String>> future = processedJobs.map(m -> m.msg).limit(10).runWith(Sink.seq(), mat);
         List<String> got = future.toCompletableFuture().get(1, TimeUnit.SECONDS);
         assertTrue(got.contains("1 done"));
         assertTrue(got.contains("2 done"));

akka-docs/rst/java/stream/stream-cookbook.rst

@@ -54,16 +54,20 @@ collection itself, so we can just call ``mapConcat(l -> l)``.
 Draining a stream to a strict collection
 ----------------------------------------
 
-**Situation:** A finite sequence of elements is given as a stream, but a Scala collection is needed instead.
+**Situation:** A possibly unbounded sequence of elements is given as a stream, which needs to be collected into a Scala collection while ensuring boundedness
 
-In this recipe we will use the ``grouped`` stream operation that groups incoming elements into a stream of limited
-size collections (it can be seen as the almost opposite version of the "Flattening a stream of sequences" recipe
-we showed before). By using a ``grouped(MAX_ALLOWED_SIZE)`` we create a stream of groups
-with maximum size of ``MaxAllowedSeqSize`` and then we take the first element of this stream by attaching a ``Sink.head()``. What we get is a
-:class:`CompletionStage` containing a sequence with all the elements of the original up to ``MAX_ALLOWED_SIZE`` size (further
-elements are dropped).
+A common situation when working with streams is one where we need to collect incoming elements into a Scala collection.
+This operation is supported via ``Sink.seq`` which materializes into a ``CompletionStage<List<T>>``.
 
-.. includecode:: ../code/docs/stream/javadsl/cookbook/RecipeToStrict.java#draining-to-list
+The function ``limit`` or ``take`` should always be used in conjunction in order to guarantee stream boundedness, thus preventing the program from running out of memory.
+
+For example, this is best avoided:
+
+.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/cookbook/RecipeSeq.java#draining-to-list-unsafe
+
+Rather, use ``limit`` or ``take`` to ensure that the resulting ``List`` will contain only up to ``MAX_ALLOWED_SIZE`` elements:
+
+.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/cookbook/RecipeSeq.java#draining-to-list-safe
 
 Calculating the digest of a ByteString stream
 ---------------------------------------------