=doc,htp #18657 document Headers request values

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

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2009-2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+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.values.Header;
+import akka.http.javadsl.server.values.Headers;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+import org.junit.Test;
+
+public class HeaderRequestValsExampleTest extends JUnitRouteTest {
+
+  @Test
+  public void testHeaderVals() {
+    //#by-class
+    // extract the entire header instance:
+    RequestVal<Host> host = Headers.byClass(Host.class).instance();
+
+    final Route route =
+      route(
+        handleWith1(host, (ctx, h) ->
+          ctx.complete(String.format("Host header was: %s", h.host()))
+        )
+      );
+
+    // tests:
+    final HttpRequest request =
+      HttpRequest
+        .GET("http://akka.io/")
+      .addHeader(Host.create("akka.io", 80));
+    testRoute(route).run(request).assertEntity("Host header was: akka.io");
+
+    //#by-class
+  }
+
+  @Test
+  public void testHeaderByName() {
+    //#by-name
+    // extract the `value` of the header:
+    final RequestVal<String> XFishName = Headers.byName("X-Fish-Name").value();
+
+    final Route route =
+      route(
+        handleWith1(XFishName, (ctx, xFishName) ->
+          ctx.complete(String.format("The `X-Fish-Name` header's value was: %s", xFishName))
+        )
+      );
+
+    // tests:
+    final HttpRequest request =
+      HttpRequest
+        .GET("/")
+        .addHeader(RawHeader.create("X-Fish-Name", "Blippy"));
+    testRoute(route).run(request).assertEntity("The `X-Fish-Name` header's value was: Blippy");
+
+    //#by-name
+  }
+}

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

@@ -0,0 +1,33 @@
+.. _header-request-vals-java:
+
+Request Values: Headers
+=======================
+
+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

@@ -25,21 +25,21 @@ Predefined Request values
 akka-http provides a set of predefined request values for request data commonly accessed in a web
 service.
 
-These request values are defined:
+These request values are defined in the following objects:
 
-RequestVals
+akka.http.javadsl.server.values.FormFieldsRequestVals
   Contains request values for basic data like URI components, request method, peer address, or the entity data.
-Cookies
+akka.http.javadsl.server.values.FormFieldsCookies
   Contains request values representing cookies.
-FormFields
+akka.http.javadsl.server.values.FormFields
   Contains request values to access form fields unmarshalled to various primitive Java types.
-Headers
+:ref:`akka.http.javadsl.server.values.Headers <header-request-vals-java>`
   Contains request values to access request headers or header values.
-HttpBasicAuthenticator
+akka.http.javadsl.server.values.FormFieldsHttpBasicAuthenticator
   An abstract class to implement to create a request value representing a HTTP basic authenticated principal.
-Parameters
+akka.http.javadsl.server.values.FormFieldsParameters
   Contains request values to access URI paramaters unmarshalled to various primitive Java types.
-PathMatchers
+akka.http.javadsl.server.values.FormFieldsPathMatchers
   Contains request values to match and access URI path segments.
-CustomRequestVal
+akka.http.javadsl.server.values.FormFieldsCustomRequestVal
   An abstract class to implement arbitrary custom request values.