Document asSubscriber stage (#28128)

* Unfortunately it seems the jdk9-only tests could not actually be compiled.
With these changes those can actually be compiled and ran again.

* Always link to jdk11 for java.* javadocs

* Update sbt-paradox-akka to fix linking to inner classes for javadoc

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

@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package jdocs.stream.operators.source;
+
+//#imports
+import java.util.concurrent.Flow.Subscriber;
+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 AsSubscriber {
+    static class JavaFlowSupport {
+        public static final class Source {
+            public
+            // #api
+            static <T> akka.stream.javadsl.Source<T, Subscriber<T>> asSubscriber()
+            // #api
+            {
+                return akka.stream.javadsl.JavaFlowSupport.Source.<T>asSubscriber();
+            }
+        }
+    }
+
+    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 {
+        Source<Row, NotUsed> rowSource =
+                JavaFlowSupport.Source.<Row>asSubscriber()
+                        .mapMaterializedValue(
+                                subscriber -> {
+                                    // For each materialization, fetch the rows from the database:
+                                    Publisher<Row> rows = databaseClient.fetchRows();
+                                    rows.subscribe(subscriber);
+
+                                    return NotUsed.getInstance();
+                                });
+
+        public Source<String, NotUsed> names() {
+            // rowSource can be re-used, since it will start a new
+            // query for each materialization, fully supporting backpressure
+            // for each materialized stream:
+            return rowSource.map(row -> row.getField("name"));
+        }
+    }
+    // #example
+}

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2019 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 AsSubscriber {
+    case class Row(name: String)
+
+    class DatabaseClient {
+        def fetchRows(): Publisher[Row] = ???
+    }
+
+    val databaseClient: DatabaseClient = ???;
+
+    // #example
+    val rowSource: Source[Row, NotUsed] =
+      JavaFlowSupport.Source.asSubscriber
+        .mapMaterializedValue(
+          (subscriber: Subscriber[Row]) => {
+            // For each materialization, fetch the rows from the database:
+            val rows: Publisher[Row] = databaseClient.fetchRows()
+            rows.subscribe(subscriber)
+            NotUsed
+          });
+
+    val names: Source[String, NotUsed] =
+      // rowSource can be re-used, since it will start a new
+      // query for each materialization, fully supporting backpressure
+      // for each materialized stream:
+      rowSource.map(row => row.name);
+    //#example
+}