Merge pull request #26294 from akka/wip-discovery-stable-patriknw

Make discovery and dns APIs stable

akka-actor/src/main/scala/akka/io/dns/CachePolicy.scala

@@ -4,20 +4,16 @@
 
 package akka.io.dns
 
-import akka.annotation.ApiMayChange
 import akka.util.JavaDurationConverters._
 
 import scala.concurrent.duration.{ Duration, FiniteDuration, _ }
 
 object CachePolicy {
 
-  @ApiMayChange
   sealed trait CachePolicy
-  @ApiMayChange
   case object Never extends CachePolicy
-  @ApiMayChange
   case object Forever extends CachePolicy
-  @ApiMayChange
+
   final class Ttl private (val value: FiniteDuration) extends CachePolicy {
     if (value <= Duration.Zero) throw new IllegalArgumentException(s"TTL values must be a positive value.")
     import akka.util.JavaDurationConverters._
@@ -32,7 +28,7 @@ object CachePolicy {
 
     override def toString = s"Ttl($value)"
   }
-  @ApiMayChange
+
   object Ttl {
     def unapply(ttl: Ttl): Option[FiniteDuration] = Some(ttl.value)
     def fromPositive(value: FiniteDuration): Ttl = {
@@ -45,7 +41,7 @@ object CachePolicy {
     val effectivelyForever: Ttl = fromPositive(Int.MaxValue.seconds)
 
     implicit object TtlIsOrdered extends Ordering[Ttl] {
-      def compare(a: Ttl, b: Ttl) = a.value.compare(b.value)
+      def compare(a: Ttl, b: Ttl): Int = a.value.compare(b.value)
     }
   }
 

akka-actor/src/main/scala/akka/io/dns/DnsProtocol.scala

@@ -7,7 +7,6 @@ package akka.io.dns
 import java.util
 
 import akka.actor.NoSerializationVerificationNeeded
-import akka.annotation.ApiMayChange
 
 import scala.collection.{ immutable ⇒ im }
 import scala.collection.JavaConverters._
@@ -21,10 +20,8 @@ import scala.collection.JavaConverters._
  * and responses can more information than plain IP addresses (e.g. ports for SRV records).
  *
  */
-@ApiMayChange
 object DnsProtocol {
 
-  @ApiMayChange
   sealed trait RequestType
   final case class Ip(ipv4: Boolean = true, ipv6: Boolean = true) extends RequestType
   final case object Srv extends RequestType
@@ -65,7 +62,6 @@ object DnsProtocol {
    * @param records resource records for the query
    * @param additionalRecords records that relate to the query but are not strictly answers
    */
-  @ApiMayChange
   final case class Resolved(name: String, records: im.Seq[ResourceRecord], additionalRecords: im.Seq[ResourceRecord]) extends NoSerializationVerificationNeeded {
     /**
      * Java API
@@ -82,10 +78,8 @@ object DnsProtocol {
     def getAdditionalRecords(): util.List[ResourceRecord] = additionalRecords.asJava
   }
 
-  @ApiMayChange
   object Resolved {
 
-    @ApiMayChange
     def apply(name: String, records: im.Seq[ResourceRecord]): Resolved =
       new Resolved(name, records, Nil)
   }

akka-actor/src/main/scala/akka/io/dns/DnsResourceRecords.scala

@@ -7,7 +7,7 @@ package akka.io.dns
 import java.net.{ Inet4Address, Inet6Address, InetAddress }
 
 import akka.actor.NoSerializationVerificationNeeded
-import akka.annotation.{ ApiMayChange, InternalApi }
+import akka.annotation.InternalApi
 import CachePolicy._
 import akka.io.dns.internal.{ DomainName, _ }
 import akka.util.{ ByteIterator, ByteString, unused }
@@ -15,12 +15,10 @@ import akka.util.{ ByteIterator, ByteString, unused }
 import scala.annotation.switch
 import scala.concurrent.duration._
 
-@ApiMayChange
 sealed abstract class ResourceRecord(val name: String, val ttl: Ttl, val recType: Short, val recClass: Short)
   extends NoSerializationVerificationNeeded {
 }
 
-@ApiMayChange
 final case class ARecord(override val name: String, override val ttl: Ttl,
                          ip: InetAddress) extends ResourceRecord(name, ttl, RecordType.A.code, RecordClass.IN.code) {
 }
@@ -37,7 +35,6 @@ private[dns] object ARecord {
   }
 }
 
-@ApiMayChange
 final case class AAAARecord(override val name: String, override val ttl: Ttl,
                             ip: Inet6Address) extends ResourceRecord(name, ttl, RecordType.AAAA.code, RecordClass.IN.code) {
 }
@@ -59,7 +56,6 @@ private[dns] object AAAARecord {
   }
 }
 
-@ApiMayChange
 final case class CNameRecord(override val name: String, override val ttl: Ttl,
                              canonicalName: String) extends ResourceRecord(name, ttl, RecordType.CNAME.code, RecordClass.IN.code) {
 }
@@ -75,7 +71,6 @@ private[dns] object CNameRecord {
   }
 }
 
-@ApiMayChange
 final case class SRVRecord(override val name: String, override val ttl: Ttl,
                            priority: Int, weight: Int, port: Int, target: String) extends ResourceRecord(name, ttl, RecordType.SRV.code, RecordClass.IN.code) {
 }
@@ -97,7 +92,6 @@ private[dns] object SRVRecord {
   }
 }
 
-@ApiMayChange
 final case class UnknownRecord(override val name: String, override val ttl: Ttl,
                                override val recType: Short, override val recClass: Short,
                                data: ByteString) extends ResourceRecord(name, ttl, recType, recClass) {

akka-actor/src/main/scala/akka/io/dns/RecordType.scala

@@ -10,10 +10,8 @@ import akka.util.OptionVal
 /**
  * DNS Record Type
  */
-@ApiMayChange
 final case class RecordType(code: Short, name: String)
 
-@ApiMayChange
 object RecordType {
   /**
    * array for fast lookups by id

akka-discovery/src/main/scala/akka/discovery/ServiceDiscovery.scala

@@ -10,14 +10,13 @@ import java.util.concurrent.CompletionStage
 import java.util.concurrent.TimeUnit
 
 import scala.collection.immutable
+import scala.compat.java8.OptionConverters._
 import scala.concurrent.Future
 import scala.concurrent.duration.FiniteDuration
 
 import akka.actor.DeadLetterSuppression
-import akka.annotation.ApiMayChange
 import akka.util.HashCode
 
-@ApiMayChange
 object ServiceDiscovery {
 
   object Resolved {
@@ -90,18 +89,14 @@ object ServiceDiscovery {
     /**
      * Java API
      */
-    def getPort: Optional[Int] = {
+    def getPort: Optional[Int] =
-      import scala.compat.java8.OptionConverters._
       port.asJava
-    }
 
     /**
      * Java API
      */
-    def getAddress: Optional[InetAddress] = {
+    def getAddress: Optional[InetAddress] =
-      import scala.compat.java8.OptionConverters._
       address.asJava
-    }
 
     override def toString: String = s"ResolvedTarget($host,$port,$address)"
 
@@ -130,7 +125,6 @@ object ServiceDiscovery {
  *
  * @throws IllegalArgumentException if [[serviceName]] is 'null' or an empty String
  */
-@ApiMayChange
 final class Lookup(
   val serviceName: String,
   val portName:    Option[String],
@@ -151,6 +145,18 @@ final class Lookup(
    */
   def withProtocol(value: String): Lookup = copy(protocol = Some(value))
 
+  /**
+   * Java API
+   */
+  def getPortName: Optional[String] =
+    portName.asJava
+
+  /**
+   * Java API
+   */
+  def getProtocol: Optional[String] =
+    protocol.asJava
+
   private def copy(
     serviceName: String         = serviceName,
     portName:    Option[String] = portName,
@@ -174,7 +180,6 @@ final class Lookup(
 
 }
 
-@ApiMayChange
 case object Lookup {
 
   /**
@@ -245,7 +250,6 @@ case object Lookup {
  * Implement to provide a service discovery method
  *
  */
-@ApiMayChange
 abstract class ServiceDiscovery {
 
   import ServiceDiscovery._

akka-docs/src/main/paradox/discovery/index.md

@@ -1,12 +1,5 @@
 # Discovery
 
-@@@ warning
-
-This module is currently marked as @ref:[may change](../common/may-change.md)
-This means that API or semantics can change without warning or deprecation period.
-
-@@@
-
 Akka Discovery provides an interface around various ways of locating services. The built in methods are:
 
 * Configuration

build.sbt

@@ -493,7 +493,6 @@ lazy val discovery = akkaModule("akka-discovery")
     actorTests % "test->test"
   )
   .settings(Dependencies.discovery)
-  .settings(AkkaBuild.mayChangeSettings)
   .settings(AutomaticModuleName.settings("akka.discovery"))
   .settings(OSGi.discovery)