=doc,htp #18657 document FormField vals

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

@@ -0,0 +1,75 @@
+/*
+ * Copyright (C) 2009-2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.javadsl.server;
+
+import akka.http.javadsl.model.ContentTypes;
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.headers.RawHeader;
+import akka.http.javadsl.server.Marshallers;
+import akka.http.javadsl.server.RequestVal;
+import akka.http.javadsl.server.Route;
+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 docs.http.scaladsl.server.directives.Person;
+import org.junit.Test;
+
+public class FormFieldRequestValsExampleTest extends JUnitRouteTest {
+
+  @Test
+  public void testFormFieldVals() {
+    //#simple
+    FormField<String> name = FormFields.stringValue("name");
+    FormField<Integer> age = FormFields.intValue("age");
+
+    final Route route =
+      route(
+        handleWith2(name, age, (ctx, n, a) ->
+          ctx.complete(String.format("Name: %s, age: %d", n, a))
+        )
+      );
+
+    // tests:
+    final HttpRequest request =
+      HttpRequest
+        .POST("/");
+        // .withFormData(); // FIXME awaits resolution of https://github.com/akka/akka/issues/18665
+    testRoute(route).run(request).assertEntity("Name: ..., age: ...");
+
+    //#simple
+  }
+
+  @Test
+  public void testFormFieldValsUnmarshaling() {
+    //#custom-unmarshal
+    FormField<SampleId> sampleId =  FormFields.fromString("id", s -> new SampleId(Integer.valueOf(s)), SampleId.class);
+
+    final Route route =
+      route(
+        handleWith1(sampleId, (ctx, id) ->
+          ctx.complete(String.format("SampleId: %s", id))
+        )
+      );
+
+    // tests:
+    final HttpRequest request =
+      HttpRequest
+        .POST("/");
+        // .withFormData(); // FIXME awaits resolution of https://github.com/akka/akka/issues/18665
+    testRoute(route).run(request).assertEntity("Name: ..., age: ...");
+
+    //#custom-unmarshal
+  }
+
+  static class SampleId {
+    public final int id;
+
+    SampleId(int id) {
+      this.id = id;
+    }
+  }
+
+}

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

@@ -5,13 +5,10 @@
 package docs.http.javadsl.server;
 
 import akka.http.javadsl.model.HttpRequest;
-//#by-class
 import akka.http.javadsl.model.headers.Host;
-
-//#by-class
 import akka.http.javadsl.model.headers.RawHeader;
-import akka.http.javadsl.server.*;
+import akka.http.javadsl.server.RequestVal;
-import akka.http.javadsl.server.values.Header;
+import akka.http.javadsl.server.Route;
 import akka.http.javadsl.server.values.Headers;
 import akka.http.javadsl.testkit.JUnitRouteTest;
 import org.junit.Test;

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

@@ -0,0 +1,33 @@
+.. _form-field-request-vals-java:
+
+Request Values: FormFields
+==========================
+
+A collection of pre-defined :ref:`request-vals-java` that can be used to extract header values from incoming requests.
+
+Description
+-----------
+Header request values allow extracting ``HttpHeader`` 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])``
+
+.. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
+   :include: by-class
+
+``Headers.byName(String)``
+
+.. includecode:: ../../../code/docs/http/javadsl/server/HeaderRequestValsExampleTest.java
+   :include: by-name

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

@@ -27,7 +27,7 @@ service.
 
 These request values are defined in the following objects:
 
-akka.http.javadsl.server.values.FormFieldsRequestVals
+:ref:`akka.http.javadsl.server.values.FormFields <form-field-request-vals-java>`
   Contains request values for basic data like URI components, request method, peer address, or the entity data.
 akka.http.javadsl.server.values.FormFieldsCookies
   Contains request values representing cookies.

akka-http/src/main/scala/akka/http/javadsl/server/values/FormField.scala

@@ -36,6 +36,7 @@ object FormFields {
   def hexIntValue(name: String): FormField[jl.Integer] = FormFieldImpl(name.as(Unmarshaller.HexInt))
   def hexLongValue(name: String): FormField[jl.Long] = FormFieldImpl(name.as(Unmarshaller.HexLong))
 
+  /** Unmarshals the `name` field using the provided `convert` function. */
   def fromString[T](name: String, convert: Function[String, T], clazz: Class[T]): FormField[T] = {
     implicit val tTag: ClassTag[T] = ClassTag(clazz)
     FormFieldImpl(name.as(Util.fromStringUnmarshallerFromFunction(convert)))