Add docs and examples for RS fromPublisher #25468

akka-docs/src/test/java-jdk9-only/jdocs/stream/operators/source/AsSubscriber.java

@@ -17,6 +17,8 @@ import akka.stream.javadsl.JavaFlowSupport;
 import org.apache.commons.lang.NotImplementedException;
 
 public interface AsSubscriber {
+    // We are 'faking' the JavaFlowSupport API here so we can include the signature as a snippet in the API,
+    // because we're not publishing those (jdk9+) classes in our API docs yet.
     static class JavaFlowSupport {
         public static final class Source {
             public

akka-docs/src/test/java-jdk9-only/jdocs/stream/operators/source/FromPublisher.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2019-2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.source;
+
+//#imports
+import java.util.concurrent.Flow.Publisher;
+
+import akka.NotUsed;
+import akka.stream.javadsl.Source;
+import akka.stream.javadsl.JavaFlowSupport;
+
+//#imports
+
+import org.apache.commons.lang.NotImplementedException;
+
+public interface FromPublisher {
+    // We are 'faking' the JavaFlowSupport API here so we can include the signature as a snippet in the API,
+    // because we're not publishing those (jdk9+) classes in our API docs yet.
+    static class JavaFlowSupport {
+        public static final class Source {
+            public
+            // #api
+            static <T> akka.stream.javadsl.Source<T, NotUsed> fromPublisher(Publisher<T> publisher)
+            // #api
+            {
+                return akka.stream.javadsl.JavaFlowSupport.Source.<T>fromPublisher(publisher);
+            }
+        }
+    }
+
+    static class Row {
+        public String getField(String fieldName) {
+            throw new NotImplementedException();
+        }
+    }
+
+    static class DatabaseClient {
+        Publisher<Row> fetchRows() {
+            throw new NotImplementedException();
+        }
+    }
+
+    DatabaseClient databaseClient = null;
+
+    // #example
+    class Example {
+        public Source<String, NotUsed> names() {
+            // A new subscriber will subscribe to the supplied publisher for each
+            // materialization, so depending on whether the database client supports
+            // this the Source can be materialized more than once.
+            return JavaFlowSupport.Source.<Row>fromPublisher(databaseClient.fetchRows())
+                .map(row -> row.getField("name"));
+        }
+    }
+    // #example
+}

akka-docs/src/test/scala-jdk9-only/docs/stream/operators/source/FromPublisher.scala

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2020 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package docs.stream.operators.source;
+
+//#imports
+import java.util.concurrent.Flow.Subscriber;
+import java.util.concurrent.Flow.Publisher;
+
+import akka.NotUsed;
+import akka.stream.scaladsl.Source;
+import akka.stream.scaladsl.JavaFlowSupport;
+
+//#imports
+
+object FromPublisher {
+    case class Row(name: String)
+
+    class DatabaseClient {
+        def fetchRows(): Publisher[Row] = ???
+    }
+
+    val databaseClient: DatabaseClient = ???
+
+    // #example
+    val names: Source[String, NotUsed] =
+      // A new subscriber will subscribe to the supplied publisher for each
+      // materialization, so depending on whether the database client supports
+      // this the Source can be materialized more than once.
+      JavaFlowSupport.Source.fromPublisher(databaseClient.fetchRows())
+        .map(row => row.name);
+    //#example
+}