Adapts and improves documentation #26156

akka-docs/src/main/paradox/cluster-sharding.md

@@ -413,6 +413,8 @@ Java
 
 Note that stopped entities will be started again when a new message is targeted to the entity.
 
+If 'on stop' backoff supervision strategy is used, a final termination message must be set and used for passivation, see #ref:[Supervision](general/supervision.md#Sharding)
+
 ## Graceful Shutdown
 
 You can send the @scala[`ShardRegion.GracefulShutdown`] @java[`ShardRegion.gracefulShutdownInstance`] message

akka-docs/src/main/paradox/general/supervision.md

@@ -207,6 +207,25 @@ to recover before the persistent actor is started.
 
 > <a id="1" href="#^1">[1]</a> A failure can be indicated in two different ways; by an actor stopping or crashing.
 
+#### Supervision strategies
+
+There are two basic supervision strategies available for backoff:
+* 'On failure': The supervisor will restart the supervised actor once it crashes, but terminate if the actor stops normaly (e.g. through `context.stop`)  
+* 'On stop': The supervisor will restart the supervised actor if it terminates in any way (consider this for `PersistentActor` since they stop on persistence failures instead of crashing)
+
+#### Sharding
+If the 'on stop' strategy is used for sharded actors a final termination message should be configured and used to terminate the actor on passivation. Otherwise the supervisor will just restart the actor again.
+
+The termination message is configured with:
+
+@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded }
+
+And must be used for passivation:
+
+@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded-passivation }
+
+#### Simple backoff
+
 The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has stopped
 because of a failure, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds:
 
@@ -239,7 +258,21 @@ The above is equivalent to this Java code:
 
 @@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-fail }
 
-The `akka.pattern.BackoffOptions` can be used to customize the behavior of the back-off supervisor actor, below are some examples:
+#### Customization
+
+The `akka.pattern.BackoffOnFailureOptions` and `akka.pattern.BackoffOnRestartOptions` can be used to customize the behavior of the back-off supervisor actor.
+Options are:
+* `withAutoReset`: The backoff is reset if no failure/stop occurs within the duration. This is the default behaviour with `minBackoff` as default value
+* `withManualReset`: The child must send `BackoffSupervisor.Reset` to its backoff supervisor (parent)
+* `withSupervisionStrategy`: Sets a custom `OneForOneStrategy` (as each backoff supervisor only has one child). The default strategy uses the `akka.actor.SupervisorStrategy.defaultDecider` which restarts on exceptions.
+* `withDefaultStoppingStrategy`: Sets a `OneForOneStrategy` with the stopping decider that stops the child on all exceptions.
+* `withMaxNrOfRetries`: Sets the maximum number of retries until the supervisor will give up (`-1` is default which means no limit of retries). Note: This is set on the supervision strategy, so setting a different strategy resets the `maxNrOfRetries`.
+* `withReplyWhileStopped`: By default all messages received while the child is stopped are forwarded to dead letters. With this set, the supervisor will reply to the sender instead.
+
+Only available on `BackoffOnStopOptions`:
+* `withFinalStopMessage`: Allows to define a predicate to decide on finally stopping the child (and supervisor). Used for passivate sharded actors - see above.
+
+Some examples:
 
 @@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-stop }
 

akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java

@@ -6,6 +6,7 @@ package jdocs.pattern;
 
 import akka.actor.*;
 import akka.pattern.Backoff;
+import akka.pattern.BackoffOpts;
 import akka.pattern.BackoffSupervisor;
 import akka.testkit.TestActors.EchoActor;
 // #backoff-imports
@@ -20,7 +21,7 @@ public class BackoffSupervisorDocTest {
 
     final Props supervisorProps =
         BackoffSupervisor.props(
-            Backoff.onStop(
+            BackoffOpts.onStop(
                 childProps,
                 "myEcho",
                 Duration.ofSeconds(3),
@@ -37,7 +38,7 @@ public class BackoffSupervisorDocTest {
 
     final Props supervisorProps =
         BackoffSupervisor.props(
-            Backoff.onFailure(
+            BackoffOpts.onFailure(
                 childProps,
                 "myEcho",
                 Duration.ofSeconds(3),

akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala

@@ -4,7 +4,8 @@
 
 package docs.pattern
 
-import akka.actor.{ ActorSystem, OneForOneStrategy, Props, SupervisorStrategy }
+import akka.actor.{ ActorContext, ActorSystem, OneForOneStrategy, Props, SupervisorStrategy }
+import akka.cluster.sharding.ShardRegion.Passivate
 import akka.pattern.{ BackoffOpts, BackoffSupervisor }
 import akka.testkit.TestActors.EchoActor
 
@@ -99,4 +100,27 @@ class BackoffSupervisorDocSpec {
 
   case class MyException(msg: String) extends Exception(msg)
 
+  case object StopMessage
+
+  class BackoffSupervisorDocSpecExampleSharding {
+    val system: ActorSystem = ???
+    val context: ActorContext = ???
+    import scala.concurrent.duration._
+
+    val childProps = Props(classOf[EchoActor])
+
+    //#backoff-sharded
+    val supervisor = BackoffSupervisor.props(BackoffOpts.onStop(
+      childProps,
+      childName = "myEcho",
+      minBackoff = 3.seconds,
+      maxBackoff = 30.seconds,
+      randomFactor = 0.2
+    ).withFinalStopMessage(_ == StopMessage))
+    //#backoff-sharded
+
+    //#backoff-sharded-passivation
+    context.parent ! Passivate(StopMessage)
+    //#backoff-sharded-passivation
+  }
 }