From dcdaa5a0dda01c4de526839c2a3e0de1b299a7aa Mon Sep 17 00:00:00 2001
From: Evgeny Sidorov <sievmi@mail.ru>
Date: Tue, 11 Feb 2020 16:58:00 +0300
Subject: [PATCH] Example for Source.fromIterator #25468 (#28582)

* add example for Source.fromIterator #25468

* scala fmt code style fix

* don't use test as a sample for docs
---
 .../stream/operators/Source/fromIterator.md   |  9 +++++++
 .../jdocs/stream/operators/source/From.java   | 26 +++++++++++++++++++
 .../docs/stream/operators/source/From.scala   | 24 +++++++++++++++++
 .../java/akka/stream/javadsl/SourceTest.java  | 13 ++++++++++
 4 files changed, 72 insertions(+)
 create mode 100644 akka-docs/src/test/java/jdocs/stream/operators/source/From.java
 create mode 100644 akka-docs/src/test/scala/docs/stream/operators/source/From.scala

diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md
index 3258c439af..f46fec5a52 100644
--- a/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md
+++ b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md
@@ -19,6 +19,15 @@ for each materialization, which is the reason the @scala[`method`] @java[`factor
 
 If the iterator perform blocking operations, make sure to run it on a separate dispatcher.
 
+## Example
+ 
+Scala
+:   @@snip [From.scala](/akka-docs/src/test/scala/docs/stream/operators/source/From.scala) { #from-iterator }
+
+Java
+:   @@snip [From.java](/akka-docs/src/test/java/jdocs/stream/operators/source/From.java) { #from-iterator }
+
+
 ## Reactive Streams semantics
 
 @@@div { .callout }
diff --git a/akka-docs/src/test/java/jdocs/stream/operators/source/From.java b/akka-docs/src/test/java/jdocs/stream/operators/source/From.java
new file mode 100644
index 0000000000..b1dbef700f
--- /dev/null
+++ b/akka-docs/src/test/java/jdocs/stream/operators/source/From.java
@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.source;
+
+import akka.actor.ActorSystem;
+import akka.stream.javadsl.Source;
+
+import java.util.Arrays;
+
+public class From {
+
+  private ActorSystem system = null;
+
+  void fromIteratorSample() {
+    // #from-iterator
+    Source.fromIterator(() -> Arrays.asList(1, 2, 3).iterator())
+        .runForeach(System.out::println, system);
+    // could print
+    // 1
+    // 2
+    // 3
+    // #from-iterator
+  }
+}
diff --git a/akka-docs/src/test/scala/docs/stream/operators/source/From.scala b/akka-docs/src/test/scala/docs/stream/operators/source/From.scala
new file mode 100644
index 0000000000..7d034a75d6
--- /dev/null
+++ b/akka-docs/src/test/scala/docs/stream/operators/source/From.scala
@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.source
+
+import akka.actor.ActorSystem
+import akka.stream.scaladsl.Source
+
+object From {
+
+  implicit val system: ActorSystem = null
+
+  def fromIteratorSample(): Unit = {
+    //#from-iterator
+    Source.fromIterator(() => (1 to 3).iterator).runForeach(println)
+    // could print
+    // 1
+    // 2
+    // 3
+    //#from-iterator
+  }
+
+}
diff --git a/akka-stream-tests/src/test/java/akka/stream/javadsl/SourceTest.java b/akka-stream-tests/src/test/java/akka/stream/javadsl/SourceTest.java
index e0b71cbdc5..028fe4970c 100644
--- a/akka-stream-tests/src/test/java/akka/stream/javadsl/SourceTest.java
+++ b/akka-stream-tests/src/test/java/akka/stream/javadsl/SourceTest.java
@@ -22,6 +22,7 @@ import akka.stream.stage.*;
 import akka.testkit.AkkaSpec;
 import akka.stream.testkit.TestPublisher;
 import akka.testkit.javadsl.TestKit;
+import com.google.common.collect.Iterables;
 import org.junit.ClassRule;
 import org.junit.Test;
 import scala.concurrent.duration.FiniteDuration;
@@ -1157,4 +1158,16 @@ public class SourceTest extends StreamTest {
         akka.stream.scaladsl.Source.empty();
     Source<Integer, NotUsed> javaSource = scalaSource.asJava();
   }
+
+  @Test
+  public void mustProperlyIterate() throws Exception {
+    final Creator<Iterator<Boolean>> input = () -> Iterables.cycle(false, true).iterator();
+
+    final CompletableFuture<List<Boolean>> future =
+        Source.fromIterator(input).grouped(10).runWith(Sink.head(), system).toCompletableFuture();
+
+    assertArrayEquals(
+        new Boolean[] {false, true, false, true, false, true, false, true, false, true},
+        future.get(1, TimeUnit.SECONDS).toArray());
+  }
 }