add InternalStableApi annotation (#26949)

akka-actor/src/main/java/akka/annotation/InternalStableApi.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2017-2019 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package akka.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks internal members that shouldn't be changed without considering possible usage outside of
+ * the Akka core modules.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS) // to be accessible by MiMa
+@Target({
+  ElementType.METHOD,
+  ElementType.CONSTRUCTOR,
+  ElementType.FIELD,
+  ElementType.TYPE,
+  ElementType.PACKAGE
+})
+public @interface InternalStableApi {}

akka-cluster-sharding/src/main/scala/akka/cluster/sharding/Shard.scala

@@ -20,6 +20,7 @@ import akka.actor.Props
 import akka.actor.Stash
 import akka.actor.Terminated
 import akka.actor.Timers
+import akka.annotation.InternalStableApi
 import akka.cluster.Cluster
 import akka.cluster.ddata.ORSet
 import akka.cluster.ddata.ORSetKey
@@ -495,6 +496,7 @@ private[akka] class Shard(
     getOrCreateEntity(id).tell(payload, snd)
   }
 
+  @InternalStableApi
   def getOrCreateEntity(id: EntityId): ActorRef = {
     val name = URLEncoder.encode(id, "utf-8")
     context.child(name) match {

akka-cluster-tools/src/main/scala/akka/cluster/singleton/ClusterSingletonManager.scala

@@ -4,40 +4,40 @@
 
 package akka.cluster.singleton
 
-import com.typesafe.config.Config
-
-import scala.concurrent.duration._
 import scala.collection.immutable
 import scala.concurrent.Future
+import scala.concurrent.Promise
+import scala.concurrent.duration._
+import scala.util.control.NonFatal
+
+import akka.AkkaException
+import akka.Done
 import akka.actor.Actor
-import akka.actor.Deploy
-import akka.actor.ActorSystem
 import akka.actor.ActorRef
 import akka.actor.ActorSelection
+import akka.actor.ActorSystem
 import akka.actor.Address
+import akka.actor.CoordinatedShutdown
 import akka.actor.DeadLetterSuppression
+import akka.actor.Deploy
 import akka.actor.FSM
+import akka.actor.NoSerializationVerificationNeeded
 import akka.actor.Props
 import akka.actor.Terminated
-import akka.cluster._
+import akka.annotation.DoNotInherit
+import akka.annotation.InternalStableApi
 import akka.cluster.ClusterEvent._
-import akka.AkkaException
-import akka.actor.NoSerializationVerificationNeeded
+import akka.cluster._
+import akka.coordination.lease.LeaseUsageSettings
+import akka.coordination.lease.scaladsl.Lease
+import akka.coordination.lease.scaladsl.LeaseProvider
+import akka.dispatch.Dispatchers
+import akka.pattern.ask
 import akka.pattern.pipe
 import akka.util.JavaDurationConverters._
-
-import scala.concurrent.Promise
-import akka.Done
-import akka.actor.CoordinatedShutdown
-import akka.annotation.DoNotInherit
-import akka.coordination.lease.LeaseUsageSettings
-import akka.pattern.ask
 import akka.util.Timeout
-import akka.coordination.lease.scaladsl.{ Lease, LeaseProvider }
-import akka.dispatch.Dispatchers
 import com.github.ghik.silencer.silent
-
-import scala.util.control.NonFatal
+import com.typesafe.config.Config
 
 object ClusterSingletonManagerSettings {
 
@@ -478,8 +478,8 @@ class ClusterSingletonManager(singletonProps: Props, terminationMessage: Any, se
     extends Actor
     with FSM[ClusterSingletonManager.State, ClusterSingletonManager.Data] {
 
-  import ClusterSingletonManager.Internal._
   import ClusterSingletonManager.Internal.OldestChangedBuffer._
+  import ClusterSingletonManager.Internal._
   import settings._
 
   val cluster = Cluster(context.system)
@@ -805,6 +805,7 @@ class ClusterSingletonManager(singletonProps: Props, terminationMessage: Any, se
       stop()
   }
 
+  @InternalStableApi
   def gotoOldest(): State = {
     val singleton = context.watch(context.actorOf(singletonProps, singletonName))
     logInfo("Singleton manager starting singleton actor [{}]", singleton.path)