+doc #20466 example snippet for akka http java dsl: FormFieldDirectives (#20731)

akka-docs/rst/java/code/docs/http/javadsl/server/directives/FormFieldDirectivesExamplesTest.java

@@ -0,0 +1,137 @@
+/*
+ * Copyright (C) 2016-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.http.javadsl.server.directives;
+
+import akka.http.javadsl.model.FormData;
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.server.Route;
+import akka.http.javadsl.server.StringUnmarshallers;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+import akka.japi.Pair;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+public class FormFieldDirectivesExamplesTest extends JUnitRouteTest {
+
+  @Test
+  public void testFormField() {
+    //#formField
+    final Route route = route(
+      formField("color", color ->
+        complete("The color is '" + color + "'")
+      ),
+      formField(StringUnmarshallers.INTEGER, "id", id ->
+        complete("The id is '" + id + "'")
+      )
+    );
+
+    // tests:
+    final FormData formData = FormData.create(Pair.create("color", "blue"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formData.toEntity()))
+      .assertEntity("The color is 'blue'");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+      .assertStatusCode(StatusCodes.BAD_REQUEST)
+      .assertEntity("Request is missing required form field 'color'");
+    //#formField
+  }
+
+  @Test
+  public void testFormFieldMap() {
+    //#formFieldMap
+    final Function<Map<String, String>, String> mapToString = map ->
+      map.entrySet()
+        .stream()
+        .map(e -> e.getKey() + " = '" + e.getValue() +"'")
+        .collect(Collectors.joining(", "));
+
+
+    final Route route = formFieldMap(fields ->
+      complete("The form fields are " + mapToString.apply(fields))
+    );
+
+    // tests:
+    final FormData formDataDiffKey =
+      FormData.create(
+        Pair.create("color", "blue"),
+        Pair.create("count", "42"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataDiffKey.toEntity()))
+      .assertEntity("The form fields are color = 'blue', count = '42'");
+
+    final FormData formDataSameKey =
+      FormData.create(
+        Pair.create("x", "1"),
+        Pair.create("x", "5"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataSameKey.toEntity()))
+      .assertEntity( "The form fields are x = '5'");
+    //#formFieldMap
+  }
+
+  @Test
+  public void testFormFieldMultiMap() {
+    //#formFieldMultiMap
+    final Function<Map<String, List<String>>, String> mapToString = map ->
+      map.entrySet()
+        .stream()
+        .map(e -> e.getKey() + " -> " + e.getValue().size())
+        .collect(Collectors.joining(", "));
+
+    final Route route = formFieldMultiMap(fields ->
+      complete("There are form fields " + mapToString.apply(fields))
+    );
+
+    // test:
+    final FormData formDataDiffKey =
+      FormData.create(
+        Pair.create("color", "blue"),
+        Pair.create("count", "42"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataDiffKey.toEntity()))
+      .assertEntity("There are form fields color -> 1, count -> 1");
+
+    final FormData formDataSameKey =
+      FormData.create(
+        Pair.create("x", "23"),
+        Pair.create("x", "4"),
+        Pair.create("x", "89"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataSameKey.toEntity()))
+      .assertEntity("There are form fields x -> 3");
+    //#formFieldMultiMap
+  }
+
+  @Test
+  public void testFormFieldList() {
+    //#formFieldList
+    final Function<List<Entry<String, String>>, String> listToString = list ->
+      list.stream()
+        .map(e -> e.getKey() + " = '" + e.getValue() +"'")
+        .collect(Collectors.joining(", "));
+
+    final Route route = formFieldList(fields ->
+      complete("The form fields are " + listToString.apply(fields))
+    );
+
+    // tests:
+    final FormData formDataDiffKey =
+      FormData.create(
+        Pair.create("color", "blue"),
+        Pair.create("count", "42"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataDiffKey.toEntity()))
+      .assertEntity("The form fields are color = 'blue', count = '42'");
+
+    final FormData formDataSameKey =
+      FormData.create(
+        Pair.create("x", "23"),
+        Pair.create("x", "4"),
+        Pair.create("x", "89"));
+    testRoute(route).run(HttpRequest.POST("/").withEntity(formDataSameKey.toEntity()))
+      .assertEntity("The form fields are x = '23', x = '4', x = '89'");
+    //#formFieldList
+  }
+}

akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formField.rst

@@ -8,4 +8,5 @@ Allows extracting a single Form field sent in the request.
 
 Example
 -------
-TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/FormFieldDirectivesExamplesTest.java#formField

akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldList.rst

@@ -17,4 +17,5 @@ can cause performance issues or even an ``OutOfMemoryError`` s.
 
 Example
 -------
-TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/FormFieldDirectivesExamplesTest.java#formFieldList

akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldMap.rst

@@ -16,4 +16,5 @@ See :ref:`-formFieldList-java-` for details.
 
 Example
 -------
-TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/FormFieldDirectivesExamplesTest.java#formFieldMap

akka-docs/rst/java/http/routing-dsl/directives/form-field-directives/formFieldMultiMap.rst

@@ -19,4 +19,5 @@ Use of this directive can result in performance degradation or even in ``OutOfMe
 
 Example
 -------
-TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/FormFieldDirectivesExamplesTest.java#formFieldMultiMap