+str #18793 StageLogging that allows logger access in stages (#21696)

* +str #18793 StageLogging that allows logger access in stages
Also, non ActorMaterializers can opt-into providing a logger here.

* +str #18794 add javadsl for StageLogging

* fix missing test method on compile only class

akka-docs/rst/scala/code/docs/stream/GraphStageLoggingDocSpec.scala

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.stream
+
+import java.util.concurrent.ThreadLocalRandom
+
+import akka.stream._
+import akka.stream.scaladsl._
+import akka.stream.stage.{ GraphStage, GraphStageLogic, OutHandler, StageLogging }
+import akka.testkit.{ AkkaSpec, EventFilter }
+
+class GraphStageLoggingDocSpec extends AkkaSpec("akka.loglevel = DEBUG") {
+
+  implicit val materializer = ActorMaterializer()
+  implicit val ec = system.dispatcher
+
+  //#stage-with-logging
+  final class RandomLettersSource extends GraphStage[SourceShape[String]] {
+    val out = Outlet[String]("RandomLettersSource.out")
+    override val shape: SourceShape[String] = SourceShape(out)
+
+    override def createLogic(inheritedAttributes: Attributes) =
+      new GraphStageLogic(shape) with StageLogging {
+        setHandler(out, new OutHandler {
+          override def onPull(): Unit = {
+            val c = nextChar() // ASCII lower case letters
+
+            // `log` is obtained from materializer automatically (via StageLogging)
+            log.debug("Randomly generated: [{}]", c)
+
+            push(out, c.toString)
+          }
+        })
+      }
+
+    def nextChar(): Char =
+      ThreadLocalRandom.current().nextInt('a', 'z'.toInt + 1).toChar
+  }
+  //#stage-with-logging
+
+  "demonstrate logging in custom graphstage" in {
+    val n = 10
+    EventFilter.debug(start = "Randomly generated", occurrences = n).intercept {
+      Source.fromGraph(new RandomLettersSource)
+        .take(n)
+        .runWith(Sink.ignore)
+        .futureValue
+    }
+  }
+
+}
+