+htc,doc #18657,#18665 FormData javadsl and FormField docs

akka-docs-dev/rst/java/code/docs/http/javadsl/server/FormFieldRequestValsExampleTest.java

@@ -5,6 +5,7 @@
 package docs.http.javadsl.server;
 
 import akka.http.javadsl.model.ContentTypes;
+import akka.http.javadsl.model.FormData;
 import akka.http.javadsl.model.HttpRequest;
 import akka.http.javadsl.model.headers.RawHeader;
 import akka.http.javadsl.server.Marshallers;
@@ -14,7 +15,9 @@ import akka.http.javadsl.server.values.FormField;
 import akka.http.javadsl.server.values.FormFields;
 import akka.http.javadsl.server.values.Headers;
 import akka.http.javadsl.testkit.JUnitRouteTest;
+import akka.japi.Pair;
 import docs.http.scaladsl.server.directives.Person;
+import org.junit.Ignore;
 import org.junit.Test;
 
 public class FormFieldRequestValsExampleTest extends JUnitRouteTest {
@@ -33,11 +36,14 @@ public class FormFieldRequestValsExampleTest extends JUnitRouteTest {
       );
 
     // tests:
+    final FormData formData = FormData.create(
+      Pair.create("name", "Blippy"),
+      Pair.create("age", "42"));
     final HttpRequest request =
       HttpRequest
-        .POST("/");
-        // .withFormData(); // FIXME awaits resolution of https://github.com/akka/akka/issues/18665
-    testRoute(route).run(request).assertEntity("Name: ..., age: ...");
+        .POST("/")
+        .withEntity(formData.toEntity());
+    testRoute(route).run(request).assertEntity("Name: Blippy, age: 42");
 
     //#simple
   }
@@ -45,21 +51,22 @@ public class FormFieldRequestValsExampleTest extends JUnitRouteTest {
   @Test
   public void testFormFieldValsUnmarshaling() {
     //#custom-unmarshal
-    FormField<SampleId> sampleId =  FormFields.fromString("id", s -> new SampleId(Integer.valueOf(s)), SampleId.class);
+    FormField<SampleId> sampleId = FormFields.fromString("id", SampleId.class, s -> new SampleId(Integer.valueOf(s)));
 
     final Route route =
       route(
-        handleWith1(sampleId, (ctx, id) ->
-          ctx.complete(String.format("SampleId: %s", id))
+        handleWith1(sampleId, (ctx, sid) ->
+          ctx.complete(String.format("SampleId: %s", sid.id))
         )
       );
 
     // tests:
+    final FormData formData = FormData.create(Pair.create("id", "1337"));
     final HttpRequest request =
       HttpRequest
-        .POST("/");
-        // .withFormData(); // FIXME awaits resolution of https://github.com/akka/akka/issues/18665
-    testRoute(route).run(request).assertEntity("Name: ..., age: ...");
+        .POST("/")
+        .withEntity(formData.toEntity());
+    testRoute(route).run(request).assertEntity("SampleId: 1337");
 
     //#custom-unmarshal
   }
@@ -72,4 +79,5 @@ public class FormFieldRequestValsExampleTest extends JUnitRouteTest {
     }
   }
 
+
 }

akka-docs-dev/rst/java/http/routing-dsl/request-vals/form-field-request-vals.rst

@@ -7,27 +7,19 @@ A collection of pre-defined :ref:`request-vals-java` that can be used to extract
 
 Description
 -----------
-Header request values allow extracting ``HttpHeader`` values or concrete instances from HTTP requests.
+``FormField`` request values allow extracting fields submitted as ``application/x-www-form-urlencoded`` values or concrete instances from HTTP requests.
 
 The ``RequestVal`` builder is made up of 2 steps, initially you need to pick which Header to extract (``byName`` or
 ``byClass``) and then you need to pick if the header is optionally available or required (i.e. the route should not
 match if the header is not present in the request). This is done using one of the below depicted methods::
 
-  RequestVal<T> instance()
-  RequestVal<<Option<T>> optionalInstance()
-
-  RequestVal<String> value()
-  RequestVal<Option<String>> optionalValue()
-
 Examples
 --------
 
-``Headers.byClass(Class[HttpHeader])``
+Extracting form fields of a certain primitive type from a request:
 
-.. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
-   :include: by-class
+.. includecode:: ../../../code/docs/http/javadsl/server/FormFieldRequestValsExampleTest.java#simple
 
-``Headers.byName(String)``
+Extracting values of custom type from a request by providing a conversion function:
 
-.. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
-   :include: by-name
+.. includecode:: ../../../code/docs/http/javadsl/server/FormFieldRequestValsExampleTest.java#custom-unmarshal

akka-docs-dev/rst/java/http/routing-dsl/request-vals/header-request-vals.rst

@@ -22,12 +22,12 @@ match if the header is not present in the request). This is done using one of th
 Examples
 --------
 
-``Headers.byClass(Class[HttpHeader])``
+Extracting a header by using a specific ``Header`` class (which are pre-defined in ``akka.http.javadsl.model.headers.*``):
 
 .. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
    :include: by-class
 
-``Headers.byName(String)``
+Extracting arbitrary headers by their name, for example custom headers (usually starting with ``X-...``):
 
 .. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
    :include: by-name