Merge pull request #18847 from ktoso/wip-migration-rawquery-ktoso

=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

@@ -380,3 +380,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