=doc #18715 migration guide for Query in Akka HTTP

akka-docs-dev/rst/java/code/docs/MigrationsJava.java

@@ -1,6 +1,7 @@
 package docs;
 
 import akka.actor.Cancellable;
+import akka.http.javadsl.model.Uri;
 import akka.japi.Pair;
 import akka.japi.function.Function;
 import akka.stream.*;
@@ -11,6 +12,7 @@ import scala.concurrent.Promise;
 import scala.runtime.BoxedUnit;
 
 import java.util.concurrent.TimeUnit;
+import java.nio.charset.Charset;
 
 public class MigrationsJava {
 
@@ -135,6 +137,15 @@ public class MigrationsJava {
             }
           });
         //#flatMapConcat
+
+        Uri uri = null;
+        //#raw-query
+        final akka.japi.Option<String> theRawQueryString = uri.rawQueryString();
+        //#raw-query
+
+        //#query-param
+        final akka.japi.Option<String> aQueryParam = uri.query().get("a");
+        //#query-param
     }
 
 }

akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst

@@ -363,3 +363,43 @@ Example
 ^^^^^^^
 
 TODO
+
+Akka HTTP: Uri parsing mode relaxed-with-raw-query replaced with rawQueryString
+===============================================================================
+
+Previously Akka HTTP allowed to configure the parsing mode of an Uri's Query part (``?a=b&c=d``) to ``relaxed-with-raw-query``
+which is useful when Uris are not formatted using the usual "key/value pairs" syntax.
+
+Instead of exposing it as an option for the parser, this is now available as the ``Option<String> rawQueryString()``
+/ ``Option<String> queryString()`` methods on on ``model.Uri``.
+
+For parsing the Query part use ``Query query(Charset charset, Uri.ParsingMode mode)``.
+
+Update procedure
+----------------
+1. If the ``uri-parsing-mode`` was set to ``relaxed-with-raw-query``, remove it
+2. In places where the query string was accessed in ``relaxed-with-raw-query`` mode, use the ``rawQueryString``/``queryString`` methods instead
+3. In places where the parsed query parts (such as ``parameter``) were used, invoke parsing directly using ``uri.query().get("a")``
+
+Example
+^^^^^^^
+
+::
+
+  // config, no longer works
+  akka.http.parsing.uri-parsing-mode = relaxed-with-raw-query
+
+should be replaced by:
+
+.. includecode:: code/docs/MigrationsJava.java#raw-query
+
+And use of query parameters from ``Uri`` that looked like this:
+
+::
+
+  // This no longer works!
+  uri.parameter("name");
+
+should be replaced by:
+
+.. includecode:: code/docs/MigrationsJava.java#query-param

akka-docs-dev/rst/scala/code/docs/MigrationsScala.scala

@@ -1,5 +1,6 @@
 package docs
 
+import akka.http.scaladsl.model.Uri
 import akka.stream.scaladsl._
 import akka.stream._
 import akka.stream.stage.{ OutHandler, InHandler, GraphStageLogic, GraphStage }
@@ -198,6 +199,15 @@ class MigrationsScala extends AkkaSpec {
         }
 
         //#port-async
+
+        val uri: Uri = ???
+        //#raw-query
+        val queryPart: Option[String] = uri.rawQueryString
+        //#raw-query
+
+        //#query-param
+        val param: Option[String] = uri.query().get("a")
+        //#query-param
       }
     }
   }

akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst

@@ -409,3 +409,44 @@ Example
 should be replaced by
 
 .. includecode:: code/docs/MigrationsScala.scala#port-async
+
+Akka HTTP: Uri parsing mode relaxed-with-raw-query replaced with rawQueryString
+===============================================================================
+
+Previously Akka HTTP allowed to configure the parsing mode of an Uri's Query part (``?a=b&c=d``) to ``relaxed-with-raw-query``
+which is useful when Uris are not formatted using the usual "key/value pairs" syntax.
+
+Instead of exposing it as an option for the parser, this is now available as the ``rawQueryString(): Option[String]``
+/ ``queryString(): Option[String]`` methods on on ``model.Uri``.
+
+
+For parsing the Query part use ``query(charset: Charset = UTF8, mode: Uri.ParsingMode = Uri.ParsingMode.Relaxed): Query``.
+
+Update procedure
+----------------
+1. If the ``uri-parsing-mode`` was set to ``relaxed-with-raw-query``, remove it
+2. In places where the query string was accessed in ``relaxed-with-raw-query`` mode, use the ``rawQueryString``/``queryString`` methods instead
+3. In places where the parsed query parts (such as ``parameter``) were used, invoke parsing directly using ``uri.query().get("a")``
+
+Example
+^^^^^^^
+
+::
+
+  // config, no longer works
+  akka.http.parsing.uri-parsing-mode = relaxed-with-raw-query
+
+should be replaced by:
+
+.. includecode:: code/docs/Migrations.scala#raw-query
+
+And use of query parameters from ``Uri`` that looked like this:
+
+::
+
+  // This no longer works!
+  uri.parameter("name")
+
+should be replaced by:
+
+.. includecode:: code/docs/Migrations.scala#query-param