=doc #18657 Doc host and path directives

* also including docs of RequestVals.matchAndExtractHost
  and RequestVals.matchAndExtractHost
* and add Host.create factory methods
* add missing HttpRequest PATCH and OPTIONS
* change to val in matchAndExtractHost for
  fail fast exception

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

@@ -0,0 +1,102 @@
+/*
+ * Copyright (C) 2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.javadsl.server.directives;
+
+import java.util.Arrays;
+import java.util.regex.Pattern;
+
+import akka.http.javadsl.model.HttpMethod;
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.model.headers.Host;
+import akka.http.javadsl.server.*;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+
+import org.junit.Test;
+
+public class HostDirectivesExamplesTest extends JUnitRouteTest {
+
+  //FIXME The GET requests should work with HttpRequest.GET("/").addHeader(Host.create
+  //      instead of absolute paths. That is tracked by issue: https://github.com/akka/akka/issues/18661
+
+  @Test
+  public void testListOfHost() {
+    //#host1
+    final Route matchListOfHosts = host(
+        Arrays.asList("api.company.com", "rest.company.com"),
+        completeWithStatus(StatusCodes.OK));
+
+    testRoute(matchListOfHosts).run(HttpRequest.GET("http://api.company.com/"))
+        .assertStatusCode(StatusCodes.OK);
+    //#host1
+  }
+
+  @Test
+  public void testHostPredicate() {
+    //#host2
+    final Route shortOnly = host(hostname -> hostname.length() < 10,
+        completeWithStatus(StatusCodes.OK));
+
+    testRoute(shortOnly).run(HttpRequest.GET("http://short.com/"))
+        .assertStatusCode(StatusCodes.OK);
+
+    testRoute(shortOnly).run(HttpRequest.GET("http://verylonghostname.com/"))
+        .assertStatusCode(StatusCodes.NOT_FOUND);
+    //#host2
+  }
+
+  @Test
+  public void testExtractHost() {
+    //#extractHostname
+    final RequestVal<String> host = RequestVals.host();
+
+    final Route route = handleWith1(host,
+        (ctx, hn) -> ctx.complete("Hostname: " + hn));
+
+    testRoute(route).run(HttpRequest.GET("http://company.com:9090/"))
+        .assertEntity("Hostname: company.com");
+    //#extractHostname
+  }
+
+  @Test
+  public void testMatchAndExtractHost() {
+    //#matchAndExtractHost
+    final RequestVal<String> hostPrefix = RequestVals
+        .matchAndExtractHost(Pattern.compile("api|rest"));
+
+    final Route hostPrefixRoute = handleWith1(hostPrefix,
+        (ctx, prefix) -> ctx.complete("Extracted prefix: " + prefix));
+
+    final RequestVal<String> hostPart = RequestVals.matchAndExtractHost(Pattern
+        .compile("public.(my|your)company.com"));
+
+    final Route hostPartRoute = handleWith1(
+        hostPart,
+        (ctx, captured) -> ctx.complete("You came through " + captured
+            + " company"));
+
+    final Route route = route(hostPrefixRoute, hostPartRoute);
+
+    testRoute(route).run(HttpRequest.GET("http://api.company.com/"))
+        .assertStatusCode(StatusCodes.OK).assertEntity("Extracted prefix: api");
+
+    testRoute(route).run(HttpRequest.GET("http://public.mycompany.com/"))
+        .assertStatusCode(StatusCodes.OK)
+        .assertEntity("You came through my company");
+    //#matchAndExtractHost
+  }
+
+  @SuppressWarnings("unused")
+  @Test(expected = IllegalArgumentException.class)
+  public void testFailingMatchAndExtractHost() {
+    //#failing-matchAndExtractHost
+    // this will throw IllegalArgumentException
+    final RequestVal<String> hostRegex = RequestVals
+        .matchAndExtractHost(Pattern
+            .compile("server-([0-9]).company.(com|net|org)"));
+    //#failing-matchAndExtractHost
+  }
+
+}

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

@@ -0,0 +1,124 @@
+/*
+ * Copyright (C) 2015 Typesafe Inc. <http://www.typesafe.com>
+ */
+
+package docs.http.javadsl.server.directives;
+
+import akka.http.javadsl.model.HttpMethod;
+import akka.http.javadsl.model.HttpMethods;
+import akka.http.javadsl.model.HttpRequest;
+import akka.http.javadsl.model.StatusCodes;
+import akka.http.javadsl.server.*;
+import akka.http.javadsl.testkit.JUnitRouteTest;
+
+import org.junit.Test;
+
+public class MethodDirectivesExamplesTest extends JUnitRouteTest {
+  @Test
+  public void testDelete() {
+    //#delete
+    final Route route = delete(complete("This is a DELETE request."));
+
+    testRoute(route).run(HttpRequest.DELETE("/")).assertEntity(
+        "This is a DELETE request.");
+    //#delete
+  }
+
+  @Test
+  public void testGet() {
+    //#get
+    final Route route = get(complete("This is a GET request."));
+
+    testRoute(route).run(HttpRequest.GET("/")).assertEntity(
+        "This is a GET request.");
+    //#get
+  }
+
+  @Test
+  public void testHead() {
+    //#head
+    final Route route = head(complete("This is a HEAD request."));
+
+    testRoute(route).run(HttpRequest.HEAD("/")).assertEntity(
+        "This is a HEAD request.");
+    //#head
+  }
+
+  @Test
+  public void testOptions() {
+    //#options
+    final Route route = options(complete("This is a OPTIONS request."));
+
+    testRoute(route).run(HttpRequest.OPTIONS("/")).assertEntity(
+        "This is a OPTIONS request.");
+    //#options
+  }
+
+  @Test
+  public void testPatch() {
+    //#patch
+    final Route route = patch(complete("This is a PATCH request."));
+
+    testRoute(route).run(HttpRequest.PATCH("/").withEntity("patch content"))
+        .assertEntity("This is a PATCH request.");
+    //#patch
+  }
+
+  @Test
+  public void testPost() {
+    //#post
+    final Route route = post(complete("This is a POST request."));
+
+    testRoute(route).run(HttpRequest.POST("/").withEntity("post content"))
+        .assertEntity("This is a POST request.");
+    //#post
+  }
+
+  @Test
+  public void testPut() {
+    //#put
+    final Route route = put(complete("This is a PUT request."));
+
+    testRoute(route).run(HttpRequest.PUT("/").withEntity("put content"))
+        .assertEntity("This is a PUT request.");
+    //#put
+  }
+
+  @Test
+  public void testMethodExample() {
+    //#method-example
+    final Route route = method(HttpMethods.PUT,
+        complete("This is a PUT request."));
+
+    testRoute(route).run(HttpRequest.PUT("/").withEntity("put content"))
+        .assertEntity("This is a PUT request.");
+
+    testRoute(route).run(HttpRequest.GET("/")).assertStatusCode(
+        StatusCodes.METHOD_NOT_ALLOWED);
+    //#method-example
+  }
+
+  @Test
+  public void testExtractMethodExample() {
+    //#extractMethod
+    final RequestVal<HttpMethod> requestMethod = RequestVals.requestMethod();
+
+    final Route otherMethod = handleWith1(
+        requestMethod,
+        (ctx, method) -> ctx.complete("This " + method.value()
+            + " request, clearly is not a GET!"));
+
+    final Route route = route(get(complete("This is a GET request.")),
+        otherMethod);
+
+    testRoute(route).run(HttpRequest.GET("/")).assertEntity(
+        "This is a GET request.");
+
+    testRoute(route).run(HttpRequest.PUT("/").withEntity("put content"))
+        .assertEntity("This PUT request, clearly is not a GET!");
+
+    testRoute(route).run(HttpRequest.HEAD("/")).assertEntity(
+        "This HEAD request, clearly is not a GET!");
+    //#extractMethod
+  }
+}