Adding internal api markers and other small corrections #26156

akka-actor/src/main/scala/akka/pattern/BackoffOnRestartSupervisor.scala

@@ -6,15 +6,18 @@ package akka.pattern
 
 import akka.actor.SupervisorStrategy._
 import akka.actor.{ OneForOneStrategy, _ }
+import akka.annotation.InternalApi
 
 import scala.concurrent.duration._
 
 /**
+ * INTERNAL API
+ *
  * Back-off supervisor that stops and starts a child actor when the child actor restarts.
  * This back-off supervisor is created by using ``akka.pattern.BackoffSupervisor.props``
  * with ``akka.pattern.Backoff.onFailure``.
  */
-private class BackoffOnRestartSupervisor(
+@InternalApi private class BackoffOnRestartSupervisor(
   val childProps:    Props,
   val childName:     String,
   minBackoff:        FiniteDuration,

akka-actor/src/main/scala/akka/pattern/BackoffOnStopSupervisor.scala

@@ -6,15 +6,18 @@ package akka.pattern
 
 import akka.actor.SupervisorStrategy.{ Directive, Escalate }
 import akka.actor.{ Actor, ActorLogging, OneForOneStrategy, Props, SupervisorStrategy, Terminated }
+import akka.annotation.InternalApi
 
 import scala.concurrent.duration.FiniteDuration
 
 /**
+ * INTERNAL API
+ *
  * Back-off supervisor that stops and starts a child actor using a back-off algorithm when the child actor stops.
  * This back-off supervisor is created by using `akka.pattern.BackoffSupervisor.props`
  * with `Backoff.onStop`.
  */
-private[akka] class BackoffOnStopSupervisor(
+@InternalApi private[akka] class BackoffOnStopSupervisor(
   val childProps:    Props,
   val childName:     String,
   minBackoff:        FiniteDuration,
@@ -30,7 +33,6 @@ private[akka] class BackoffOnStopSupervisor(
   import BackoffSupervisor._
   import context.dispatcher
 
-  // to keep binary compatibility with 2.4.1
   override val supervisorStrategy = strategy match {
     case oneForOne: OneForOneStrategy ⇒
       OneForOneStrategy(oneForOne.maxNrOfRetries, oneForOne.withinTimeRange, oneForOne.loggingEnabled) {
@@ -73,8 +75,9 @@ private[akka] class BackoffOnStopSupervisor(
   protected def handleMessageToChild(msg: Any): Unit = child match {
     case Some(c) ⇒
       c.forward(msg)
-      if (!finalStopMessageReceived && finalStopMessage.isDefined) {
-        finalStopMessageReceived = finalStopMessage.get.apply(msg)
+      if (!finalStopMessageReceived) finalStopMessage match {
+        case Some(fsm) ⇒ finalStopMessageReceived = fsm(msg)
+        case None      ⇒
       }
     case None ⇒
       replyWhileStopped match {

akka-actor/src/main/scala/akka/pattern/BackoffOptions.scala

@@ -244,7 +244,7 @@ object Backoff {
    *   random delay based on this factor is added, e.g. `0.2` adds up to `20%` delay.
    *   In order to skip this additional delay pass in `0`.
    */
-  @Deprecated
+  @deprecated("Use the overloaded one which accepts maxNrOfRetries instead.", "2.5.17")
   def onFailure(
     childProps:   Props,
     childName:    String,
@@ -497,7 +497,7 @@ object Backoff {
    *   random delay based on this factor is added, e.g. `0.2` adds up to `20%` delay.
    *   In order to skip this additional delay pass in `0`.
    */
-  @Deprecated
+  @deprecated("Use the overloaded one which accepts maxNrOfRetries instead.", "2.5.17")
   def onStop(
     childProps:   Props,
     childName:    String,

akka-actor/src/main/scala/akka/pattern/BackoffSupervisor.scala

@@ -16,7 +16,7 @@ import scala.util.Try
 object BackoffSupervisor {
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor.
+   * Props for creating a `BackoffSupervisor` actor.
    *
    * Exceptions in the child are handled with the default supervision strategy, i.e.
    * most exceptions will immediately restart the child. You can define another
@@ -42,7 +42,7 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor.
+   * Props for creating a `BackoffSupervisor` actor.
    *
    * Exceptions in the child are handled with the default supervision strategy, i.e.
    * most exceptions will immediately restart the child. You can define another
@@ -76,7 +76,7 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor.
+   * Props for creating a `BackoffSupervisor` actor.
    *
    * Exceptions in the child are handled with the default supervision strategy, i.e.
    * most exceptions will immediately restart the child. You can define another
@@ -102,7 +102,7 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor.
+   * Props for creating a `BackoffSupervisor` actor.
    *
    * Exceptions in the child are handled with the default supervision strategy, i.e.
    * most exceptions will immediately restart the child. You can define another
@@ -132,7 +132,7 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor with a custom
+   * Props for creating a `BackoffSupervisor` actor with a custom
    * supervision strategy.
    *
    * Exceptions in the child are handled with the given `supervisionStrategy`. A
@@ -166,7 +166,7 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor with a custom
+   * Props for creating a `BackoffSupervisor` actor with a custom
    * supervision strategy.
    *
    * Exceptions in the child are handled with the given `supervisionStrategy`. A
@@ -197,26 +197,26 @@ object BackoffSupervisor {
   }
 
   /**
-   * Props for creating a [[BackoffSupervisor]] actor from [[BackoffOptions]].
+   * Props for creating a `BackoffSupervisor` actor from [[BackoffOptions]].
    *
    * @param options the [[BackoffOptions]] that specify how to construct a backoff-supervisor.
    */
   def props(options: BackoffOptions): Props = options.props
 
   /**
-   * Send this message to the [[BackoffSupervisor]] and it will reply with
+   * Send this message to the `BackoffSupervisor` and it will reply with
    * [[BackoffSupervisor.CurrentChild]] containing the `ActorRef` of the current child, if any.
    */
   final case object GetCurrentChild
 
   /**
-   * Java API: Send this message to the [[BackoffSupervisor]] and it will reply with
+   * Java API: Send this message to the `BackoffSupervisor` and it will reply with
    * [[BackoffSupervisor.CurrentChild]] containing the `ActorRef` of the current child, if any.
    */
   def getCurrentChild = GetCurrentChild
 
   /**
-   * Send this message to the [[BackoffSupervisor]] and it will reply with
+   * Send this message to the `BackoffSupervisor` and it will reply with
    * [[BackoffSupervisor.CurrentChild]] containing the `ActorRef` of the current child, if any.
    */
   final case class CurrentChild(ref: Option[ActorRef]) {
@@ -227,25 +227,25 @@ object BackoffSupervisor {
   }
 
   /**
-   * Send this message to the [[BackoffSupervisor]] and it will reset the back-off.
+   * Send this message to the `BackoffSupervisor` and it will reset the back-off.
    * This should be used in conjunction with `withManualReset` in [[BackoffOptions]].
    */
   final case object Reset
 
   /**
-   * Java API: Send this message to the [[BackoffSupervisor]] and it will reset the back-off.
+   * Java API: Send this message to the `BackoffSupervisor` and it will reset the back-off.
    * This should be used in conjunction with `withManualReset` in [[BackoffOptions]].
    */
   def reset = Reset
 
   /**
-   * Send this message to the [[BackoffSupervisor]] and it will reply with
+   * Send this message to the `BackoffSupervisor` and it will reply with
    * [[BackoffSupervisor.RestartCount]] containing the current restart count.
    */
   final case object GetRestartCount
 
   /**
-   * Java API: Send this message to the [[BackoffSupervisor]] and it will reply with
+   * Java API: Send this message to the `BackoffSupervisor` and it will reply with
    * [[BackoffSupervisor.RestartCount]] containing the current restart count.
    */
   def getRestartCount = GetRestartCount

akka-actor/src/main/scala/akka/pattern/HandleBackoff.scala

@@ -5,11 +5,14 @@
 package akka.pattern
 
 import akka.actor.{ Actor, ActorRef, Props }
+import akka.annotation.InternalApi
 
 /**
+ * INTERNAL API
+ *
  * Implements basic backoff handling for [[BackoffOnRestartSupervisor]] and [[BackoffOnStopSupervisor]].
  */
-private[akka] trait HandleBackoff {
+@InternalApi private[akka] trait HandleBackoff {
   this: Actor ⇒
   def childProps: Props
   def childName: String