+doc Add examples to Sink.actorRefWithAck (#24854)

akka-docs/src/test/scala/docs/stream/IntegrationDocSpec.scala

@@ -10,21 +10,23 @@ import scala.concurrent.duration._
 import akka.testkit.AkkaSpec
 import akka.stream.scaladsl._
 import akka.stream.ActorMaterializer
+
 import scala.concurrent.Future
 import akka.testkit.TestProbe
-import akka.actor.ActorRef
+import akka.actor.{ Actor, ActorLogging, ActorRef, Props, Status }
 import com.typesafe.config.ConfigFactory
-import akka.actor.Actor
-import akka.actor.Props
 import akka.util.Timeout
 import akka.stream.Attributes
 import akka.stream.ActorAttributes
+
 import scala.concurrent.ExecutionContext
 import akka.stream.ActorMaterializerSettings
 import java.util.concurrent.atomic.AtomicInteger
+
 import akka.stream.Supervision
 import akka.stream.scaladsl.Flow
 import akka.Done
+import akka.actor.Status.Status
 
 object IntegrationDocSpec {
   import TwitterStreamQuickstartDocSpec._
@@ -195,6 +197,63 @@ class IntegrationDocSpec extends AkkaSpec(IntegrationDocSpec.config) {
     probe.expectMsg("akkateam@somewhere.com")
   }
 
+  "actorRefWithAck" in {
+    //#actorRefWithAck
+    val words: Source[String, NotUsed] =
+      Source(List("hello", "hi"))
+
+    // sent from actor to stream to "ack" processing of given element
+    val AckMessage = AckingReceiver.Ack
+
+    // sent from stream to actor to indicate start, end or failure of stream:
+    val InitMessage = AckingReceiver.StreamInitialized
+    val OnCompleteMessage = AckingReceiver.StreamCompleted
+    val onErrorMessage = (ex: Throwable) ⇒ AckingReceiver.StreamFailure(ex)
+
+    val receiver = system.actorOf(
+      Props(new AckingReceiver(ackWith = AckMessage)))
+    val sink = Sink.actorRefWithAck(
+      receiver,
+      onInitMessage = InitMessage,
+      ackMessage = AckMessage,
+      onCompleteMessage = OnCompleteMessage,
+      onFailureMessage = onErrorMessage
+    )
+
+    words
+      .map(_.toLowerCase)
+      .runWith(sink)
+    //#actorRefWithAck
+  }
+
+  //#actorRefWithAck-actor
+  object AckingReceiver {
+    case object Ack
+
+    case object StreamInitialized
+    case object StreamCompleted
+    final case class StreamFailure(ex: Throwable)
+  }
+
+  class AckingReceiver(ackWith: Any) extends Actor with ActorLogging {
+    import AckingReceiver._
+
+    def receive: Receive = {
+      case StreamInitialized ⇒
+        log.info("Stream initialized!")
+
+      case el: String ⇒
+        log.info("Received element: {}", el)
+        sender() ! Ack // ack to allow the stream to proceed sending more elements
+
+      case StreamCompleted ⇒
+        log.info("Stream completed!")
+      case StreamFailure(ex) ⇒
+        log.error(ex, "Stream failed!")
+    }
+  }
+  //#actorRefWithAck-actor
+
   "lookup email with mapAsync and supervision" in {
     val addressSystem = new AddressSystem2
     val authors: Source[Author, NotUsed] =