Docs for lazy stream operators (#28897)

akka-docs/src/test/java/jdocs/stream/operators/flow/Lazy.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.flow;
+/*
+ * Copyright (C) 2009-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+import akka.NotUsed;
+import akka.actor.ActorSystem;
+import akka.japi.Pair;
+import akka.stream.javadsl.Flow;
+import akka.stream.javadsl.RunnableGraph;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+public class Lazy {
+  private ActorSystem system = null;
+
+  void example() {
+    // #simple-example
+    Source<Integer, NotUsed> numbers =
+        Source.unfold(
+                0,
+                n -> {
+                  int next = n + 1;
+                  System.out.println("Source producing " + next);
+                  return Optional.of(Pair.create(next, next));
+                })
+            .take(3);
+
+    Flow<Integer, Integer, CompletionStage<NotUsed>> flow =
+        Flow.lazyFlow(
+            () -> {
+              System.out.println("Creating the actual flow");
+              return Flow.fromFunction(
+                  element -> {
+                    System.out.println("Actual flow mapped " + element);
+                    return element;
+                  });
+            });
+
+    numbers.via(flow).run(system);
+    // prints:
+    // Source producing 1
+    // Creating the actual flow
+    // Actual flow mapped 1
+    // Source producing 2
+    // Actual flow mapped 2
+    // #simple-example
+  }
+
+  void statefulMap() {
+    // #mutable-example
+    Flow<Integer, List<Integer>, CompletionStage<NotUsed>> mutableFold =
+        Flow.lazyFlow(
+            () -> {
+              List<Integer> zero = new ArrayList<>();
+
+              return Flow.of(Integer.class)
+                  .fold(
+                      zero,
+                      (list, element) -> {
+                        list.add(element);
+                        return list;
+                      });
+            });
+
+    RunnableGraph<NotUsed> stream =
+        Source.range(1, 3).via(mutableFold).to(Sink.foreach(System.out::println));
+
+    stream.run(system);
+    stream.run(system);
+    stream.run(system);
+    // prints:
+    // [1, 2, 3]
+    // [1, 2, 3]
+    // [1, 2, 3]
+    // #mutable-example
+  }
+}

akka-docs/src/test/java/jdocs/stream/operators/sink/Lazy.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.sink;
+/*
+ * Copyright (C) 2009-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+import akka.actor.ActorSystem;
+import akka.stream.javadsl.Keep;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.Source;
+
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+public class Lazy {
+
+  private ActorSystem system = null;
+
+  void example() {
+    // #simple-example
+    CompletionStage<Optional<String>> matVal =
+        Source.<String>maybe()
+            .map(
+                element -> {
+                  System.out.println("mapped " + element);
+                  return element;
+                })
+            .toMat(
+                Sink.lazySink(
+                    () -> {
+                      System.out.println("Sink created");
+                      return Sink.foreach(elem -> System.out.println("foreach " + elem));
+                    }),
+                Keep.left())
+            .run(system);
+
+    // some time passes
+    // nothing has been printed
+    matVal.toCompletableFuture().complete(Optional.of("one"));
+    // now prints:
+    // mapped one
+    // Sink created
+    // foreach one
+
+    // #simple-example
+  }
+}

akka-docs/src/test/java/jdocs/stream/operators/source/Lazy.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2009-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.source;
+
+import akka.Done;
+import akka.NotUsed;
+import akka.actor.ActorSystem;
+import akka.japi.Pair;
+import akka.stream.javadsl.RunnableGraph;
+import akka.stream.javadsl.Sink;
+import akka.stream.javadsl.SinkQueueWithCancel;
+import akka.stream.javadsl.Source;
+
+import java.util.Optional;
+import java.util.concurrent.CompletionStage;
+
+public class Lazy {
+
+  private ActorSystem system = null;
+
+  private Source<String, NotUsed> createExpensiveSource() {
+    throw new UnsupportedOperationException("Not implemented in sample");
+  }
+
+  void notReallyThatLazy() {
+    // #not-a-good-example
+    Source<String, CompletionStage<NotUsed>> source =
+        Source.lazySource(
+            () -> {
+              System.out.println("Creating the actual source");
+              return createExpensiveSource();
+            });
+
+    SinkQueueWithCancel<String> queue = source.runWith(Sink.queue(), system);
+
+    // ... time passes ...
+    // at some point in time we pull the first time
+    // but the source creation may already have been triggered
+    queue.pull();
+    // #not-a-good-example
+  }
+
+  static class IteratorLikeThing {
+    boolean thereAreMore() {
+      throw new UnsupportedOperationException("Not implemented in sample");
+    }
+
+    String extractNext() {
+      throw new UnsupportedOperationException("Not implemented in sample");
+    }
+  }
+
+  void safeMutableSource() {
+    // #one-per-materialization
+    RunnableGraph<CompletionStage<NotUsed>> stream =
+        Source.lazySource(
+                () -> {
+                  IteratorLikeThing instance = new IteratorLikeThing();
+                  return Source.unfold(
+                      instance,
+                      sameInstance -> {
+                        if (sameInstance.thereAreMore())
+                          return Optional.of(Pair.create(sameInstance, sameInstance.extractNext()));
+                        else return Optional.empty();
+                      });
+                })
+            .to(Sink.foreach(System.out::println));
+
+    // each of the three materializations will have their own instance of IteratorLikeThing
+    stream.run(system);
+    stream.run(system);
+    stream.run(system);
+    // #one-per-materialization
+  }
+}