announce ServerBuilder API briefly in release notes and migration guide

docs/src/main/paradox/migration-guide/migration-guide-10.2.x.md

@@ -12,6 +12,31 @@ If you find an unexpected incompatibility please let us know, so we can check wh
 
 ## Akka HTTP 10.1.11 -> 10.2.0
 
+### Hiding Materializer
+
+Recent Akka versions introduced a singleton system materializer that can be summoned from an ActorSystem automatically. In many cases,
+`Materializer` arguments are now optional and APIs have been simplified to require materializers in fewer places. In fact, most common
+uses do not require a materializer any more at all.
+
+### New ServerBuilder API to create server bindings
+
+To simplify binding servers (and making it more consistent between Java and Scala), a new @apidoc[ServerBuilder] API has been introduced.
+The most common change needed to bind a server to handle routes will be from:
+
+Scala
+:   @@snip [AkkaHttp1020MigrationSpec.scala]($test$/scala/docs/http/scaladsl/server/AkkaHttp1020MigrationSpec.scala) { #old-binding }
+
+Java
+:   @@snip [AkkaHttp1020MigrationExample.java]($test$/java/docs/http/javadsl/server/AkkaHttp1020MigrationExample.java) { #old-binding }
+
+to:
+
+Scala
+:   @@snip [AkkaHttp1020MigrationSpec.scala]($test$/scala/docs/http/scaladsl/server/AkkaHttp1020MigrationSpec.scala) { #new-binding }
+
+Java
+:   @@snip [AkkaHttp1020MigrationExample.java]($test$/java/docs/http/javadsl/server/AkkaHttp1020MigrationExample.java) { #new-binding }
+
 ### HTTP/2 support requires JDK 8 update 252 or later
 
 JVM support for ALPN has been backported to JDK 8u252 which is now widely available. Support for using the Jetty ALPN

docs/src/main/paradox/release-notes/10.2.x.md

@@ -1,8 +1,9 @@
 # 10.2.x Release Notes
 
-Among other things, 10.2.0-RC1 contains:
+Among other things, 10.2.0-RC2 contains:
 
 * APIs and documentation now provide a seamless experience with Akka 2.6 and the new Actor APIs. Akka HTTP 10.2.x will still be supporting Akka 2.5 to ease incremental updating.
+* A new @ref[ServerBuilder API](../migration-guide/migration-guide-10.2.x.md#new-serverbuilder-api-to-create-server-bindings) to simplify and streamline binding servers.
 * Some new features, including the ability to [attach attributes to requests and responses](https://doc.akka.io/docs/akka-http/10.2.0-M1/common/http-model.html#attributes).
 * Allow client setting overrides for target hosts @ref[via configuration](../client-side/configuration.md#per-host-overrides) [#2574](https://github.com/akka/akka-http/pull/2574)
 * Improved default configuration, such as [disabling transparent HEAD support by default](https://github.com/akka/akka-http/issues/2088).

docs/src/test/java/docs/http/javadsl/server/AkkaHttp1020MigrationExample.java

@@ -0,0 +1,39 @@
+package docs.http.javadsl.server;
+
+import akka.actor.typed.javadsl.Behaviors;
+import akka.http.javadsl.ConnectHttp;
+import akka.http.javadsl.Http;
+import static akka.http.javadsl.server.Directives.*;
+import akka.http.javadsl.server.Route;
+import akka.stream.ActorMaterializer;
+import akka.stream.Materializer;
+
+@SuppressWarnings("deprecation")
+public class AkkaHttp1020MigrationExample {
+    public static void main(String[] args) {
+        {
+            //#old-binding
+            // only worked with classic actor system
+            akka.actor.ActorSystem system = akka.actor.ActorSystem.create("TheSystem");
+            Materializer mat = ActorMaterializer.create(system);
+            Route route = get(() -> complete("Hello World!"));
+            Http.get(system).bindAndHandle(route.flow(system), ConnectHttp.toHost("localhost", 8080), mat);
+            //#old-binding
+        }
+
+        {
+            //#new-binding
+            // works with classic or typed actor system
+            akka.actor.typed.ActorSystem system = akka.actor.typed.ActorSystem.create(Behaviors.empty(), "TheSystem");
+            // or
+            // akka.actor.ActorSystem system = akka.actor.ActorSystem.create("TheSystem");
+
+            // materializer not needed any more
+
+            Route route = get(() -> complete("Hello World!"));
+            Http.get(system).newServerAt("localhost", 8080).bind(route);
+            //#new-binding
+        }
+    }
+
+}

docs/src/test/scala/docs/http/scaladsl/HttpServerHighLevel.scala

@@ -31,7 +31,7 @@ object HttpServerHighLevel {
         )
       }
 
-    // `route` will be implicitly converted to `Flow` using `RouteResult.route2HandlerFlow`
+    // `route` will be implicitly converted to an async handler
     val bindingFuture = Http().newServerAt("localhost", 8080).bind(route)
     println(s"Server online at http://localhost:8080/\nPress RETURN to stop...")
     StdIn.readLine() // let it run until user presses return

docs/src/test/scala/docs/http/scaladsl/server/AkkaHttp1020MigrationSpec.scala

@@ -0,0 +1,43 @@
+package docs.http.scaladsl.server
+
+import akka.actor.typed.scaladsl.Behaviors
+import akka.http.scaladsl.Http
+import akka.http.scaladsl.server.Route
+import akka.stream.{ ActorMaterializer, Materializer }
+import com.github.ghik.silencer.silent
+
+@silent("since 10.2.0")
+@silent("method apply in object ActorMaterializer is deprecated")
+class AkkaHttp1020MigrationSpec {
+  import akka.http.scaladsl.server.Directives._
+
+  {
+    //#old-binding
+    // only worked with classic actor system
+    implicit val system = akka.actor.ActorSystem("TheSystem")
+    implicit val mat: Materializer = ActorMaterializer()
+    val route: Route =
+      get {
+        complete("Hello world")
+      }
+    Http().bindAndHandle(route, "localhost", 8080)
+    //#old-binding
+  }
+
+  {
+    //#new-binding
+    // works with both classic and typed ActorSystem
+    implicit val system = akka.actor.typed.ActorSystem(Behaviors.empty, "TheSystem")
+    // or
+    // implicit val system = akka.actor.ActorSystem("TheSystem")
+
+    // materializer not needed any more
+
+    val route: Route =
+      get {
+        complete("Hello world")
+      }
+    Http().newServerAt("localhost", 8080).bind(route)
+    //#new-binding
+  }
+}