+doc #20466 add header directive examples (Java) (#20673)

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

@@ -0,0 +1,230 @@
+/*
+ * Copyright (C) 2015-2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+package docs.http.javadsl.server.directives;
+
+import java.util.Optional;
+import java.util.function.Function;
+
+import org.junit.Test;
+
+import akka.http.javadsl.model.HttpHeader;
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.model.headers.Host;
+import akka.http.javadsl.model.headers.HttpOrigin;
+import akka.http.javadsl.model.headers.Origin;
+import akka.http.javadsl.model.headers.RawHeader;
+import akka.http.javadsl.server.Rejections;
+import akka.http.javadsl.server.Route;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+import akka.japi.JavaPartialFunction;
+import scala.PartialFunction;
+
+public class HeaderDirectivesExamplesTest extends JUnitRouteTest {
+
+  @Test
+  public void testHeaderValue() {
+    //#headerValue
+    final Function<HttpHeader, Optional<Host>> extractHostPort = header -> {
+      if (header instanceof Host) {
+        return Optional.of((Host) header);
+      } else {
+        return Optional.empty();
+      }
+    };
+
+    final Route route = headerValue(extractHostPort, host ->
+        complete("The port was " + host.port())
+    );
+
+    // tests:
+    testRoute(route).run(HttpRequest.GET("/").addHeader(Host.create("example.com", 5043)))
+                    .assertEntity("The port was 5043");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+                    .assertStatusCode(StatusCodes.NOT_FOUND)
+                    .assertEntity("The requested resource could not be found.");
+    //#headerValue
+  }
+
+  @Test
+  public void testHeaderValueByName() {
+    //#headerValueByName
+    final Route route = headerValueByName("X-User-Id", userId ->
+        complete("The user is " + userId)
+    );
+
+    // tests:
+    final RawHeader header = RawHeader.create("X-User-Id", "Joe42");
+    testRoute(route).run(HttpRequest.GET("/").addHeader(header))
+                    .assertEntity("The user is Joe42");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+                    .assertStatusCode(StatusCodes.BAD_REQUEST)
+                    .assertEntity("Request is missing required HTTP header 'X-User-Id'");
+    //#headerValueByName
+  }
+
+  @Test
+  public void testHeaderValueByType() {
+    //#headerValueByType
+    final Route route = headerValueByType(Origin.class, origin ->
+        complete("The first origin was " + origin.getOrigins().iterator().next())
+    );
+
+    // tests:
+    final Host host = Host.create("localhost", 8080);
+    final Origin originHeader = Origin.create(HttpOrigin.create("http", host));
+
+    testRoute(route).run(HttpRequest.GET("abc").addHeader(originHeader))
+                    .assertEntity("The first origin was http://localhost:8080");
+
+    testRoute(route).run(HttpRequest.GET("abc"))
+                    .assertStatusCode(StatusCodes.BAD_REQUEST)
+                    .assertEntity("Request is missing required HTTP header 'Origin'");
+    //#headerValueByType
+  }
+
+  @Test
+  public void testHeaderValuePF() {
+    //#headerValuePF
+    final PartialFunction<HttpHeader, Integer> extractHostPort =
+        new JavaPartialFunction<HttpHeader, Integer>() {
+      @Override
+      public Integer apply(HttpHeader x, boolean isCheck) throws Exception {
+        if (x instanceof Host) {
+          if (isCheck) {
+            return null;
+          } else {
+            return ((Host) x).port();
+          }
+        } else {
+          throw noMatch();
+        }
+      }
+    };
+
+    final Route route = headerValuePF(extractHostPort, port ->
+        complete("The port was " + port)
+    );
+
+    // tests:
+    testRoute(route).run(HttpRequest.GET("/").addHeader(Host.create("example.com", 5043)))
+                    .assertEntity("The port was 5043");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+                    .assertStatusCode(StatusCodes.NOT_FOUND)
+                    .assertEntity("The requested resource could not be found.");
+    //#headerValuePF
+  }
+
+  @Test
+  public void testOptionalHeaderValue() {
+    //#optionalHeaderValue
+    final Function<HttpHeader, Optional<Integer>> extractHostPort = header -> {
+      if (header instanceof Host) {
+        return Optional.of(((Host) header).port());
+      } else {
+        return Optional.empty();
+      }
+    };
+
+    final Route route = optionalHeaderValue(extractHostPort, port -> {
+      if (port.isPresent()) {
+        return complete("The port was " + port.get());
+      } else {
+        return complete("The port was not provided explicitly");
+      }
+    });
+
+    // tests:
+    testRoute(route).run(HttpRequest.GET("/").addHeader(Host.create("example.com", 5043)))
+                    .assertEntity("The port was 5043");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+                    .assertEntity("The port was not provided explicitly");
+    //#optionalHeaderValue
+  }
+
+  @Test
+  public void testOptionalHeaderValueByName() {
+    //#optionalHeaderValueByName
+    final Route route = optionalHeaderValueByName("X-User-Id", userId -> {
+      if (userId.isPresent()) {
+        return complete("The user is " + userId.get());
+      } else {
+        return complete("No user was provided");
+      }
+    });
+
+    // tests:
+    final RawHeader header = RawHeader.create("X-User-Id", "Joe42");
+    testRoute(route).run(HttpRequest.GET("/").addHeader(header))
+                    .assertEntity("The user is Joe42");
+
+    testRoute(route).run(HttpRequest.GET("/")).assertEntity("No user was provided");
+    //#optionalHeaderValueByName
+  }
+
+  @Test
+  public void testOptionalHeaderValueByType() {
+    //#optionalHeaderValueByType
+    final Route route = optionalHeaderValueByType(Origin.class, origin -> {
+      if (origin.isPresent()) {
+        return complete("The first origin was " + origin.get().getOrigins().iterator().next());
+      } else {
+        return complete("No Origin header found.");
+      }
+    });
+
+    // tests:
+
+    // extract Some(header) if the type is matching
+    Host host = Host.create("localhost", 8080);
+    Origin originHeader = Origin.create(HttpOrigin.create("http", host));
+    testRoute(route).run(HttpRequest.GET("abc").addHeader(originHeader))
+                    .assertEntity("The first origin was http://localhost:8080");
+
+    // extract None if no header of the given type is present
+    testRoute(route).run(HttpRequest.GET("abc")).assertEntity("No Origin header found.");
+
+    //#optionalHeaderValueByType
+  }
+
+  @Test
+  public void testOptionalHeaderValuePF() {
+    //#optionalHeaderValuePF
+    final PartialFunction<HttpHeader, Integer> extractHostPort =
+        new JavaPartialFunction<HttpHeader, Integer>() {
+      @Override
+      public Integer apply(HttpHeader x, boolean isCheck) throws Exception {
+        if (x instanceof Host) {
+          if (isCheck) {
+            return null;
+          } else {
+            return ((Host) x).port();
+          }
+        } else {
+          throw noMatch();
+        }
+      }
+    };
+
+    final Route route = optionalHeaderValuePF(extractHostPort, port -> {
+      if (port.isPresent()) {
+        return complete("The port was " + port.get());
+      } else {
+        return complete("The port was not provided explicitly");
+      }
+    });
+
+    // tests:
+    testRoute(route).run(HttpRequest.GET("/").addHeader(Host.create("example.com", 5043)))
+                    .assertEntity("The port was 5043");
+
+    testRoute(route).run(HttpRequest.GET("/"))
+                    .assertEntity("The port was not provided explicitly");
+    //#optionalHeaderValuePF
+  }
+}

akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValue.rst

@@ -19,4 +19,4 @@ See also :ref:`-headerValuePF-java-` for a nicer syntactic alternative.
 
 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/HeaderDirectivesExamplesTest.java#headerValue

akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValueByName.rst

@@ -14,4 +14,4 @@ handling when the header is missing use the :ref:`-optionalHeaderValueByName-jav
 
 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/HeaderDirectivesExamplesTest.java#headerValueByName

akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValueByType.rst

@@ -19,4 +19,4 @@ is missing use the :ref:`-optionalHeaderValueByType-java-` directive instead.
 
 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/HeaderDirectivesExamplesTest.java#headerValueByType

akka-docs/rst/java/http/routing-dsl/directives/header-directives/headerValuePF.rst

@@ -16,4 +16,4 @@ If the function is not defined for any header the request is rejected as "NotFou
 
 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/HeaderDirectivesExamplesTest.java#headerValuePF

akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValue.rst

@@ -13,4 +13,4 @@ value instead of rejecting the request if no matching header could be found.
 
 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/HeaderDirectivesExamplesTest.java#optionalHeaderValue

akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValueByName.rst

@@ -12,4 +12,4 @@ an ``Optional`` value instead of rejecting the request if no matching header cou
 
 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/HeaderDirectivesExamplesTest.java#optionalHeaderValueByName

akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValueByType.rst

@@ -18,4 +18,4 @@ an ``Optional`` value instead of rejecting the request if no matching header cou
 
 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/HeaderDirectivesExamplesTest.java#optionalHeaderValueByType

akka-docs/rst/java/http/routing-dsl/directives/header-directives/optionalHeaderValuePF.rst

@@ -13,4 +13,4 @@ value instead of rejecting the request if no matching header could be found.
 
 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/HeaderDirectivesExamplesTest.java#optionalHeaderValuePF