=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/http/routing-dsl/directives/host-directives/extractHost.rst

@@ -0,0 +1,13 @@
+.. _-extractHost-java-:
+
+RequestVals.host
+================
+
+Extract the hostname part of the ``Host`` request header and expose it as a ``String`` extraction
+to its inner route.
+
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/HostDirectivesExamplesTest.java#extractHostname

akka-docs-dev/rst/java/http/routing-dsl/directives/host-directives/host.rst

@@ -0,0 +1,44 @@
+.. _-host-java-:
+
+host
+====
+
+Filter requests matching conditions against the hostname part of the Host header value
+in the request.
+
+There are a few variants:
+
+* reject all requests with a hostname different from the given ones
+* reject all requests for which the hostname does not satisfy the given predicate
+* reject all requests for which the hostname does not satisfy the given regular expression
+
+The regular expression matching works a little bit different: it rejects all requests with a hostname
+that doesn't have a prefix matching the given regular expression and also extracts a ``String`` to its
+inner route following this rules:
+
+   * For all matching requests the prefix string matching the regex is extracted and passed to the inner route.
+   * If the regex contains a capturing group only the string matched by this group is extracted.
+   * If the regex contains more than one capturing group an ``IllegalArgumentException`` is thrown.
+
+Example
+-------
+
+Matching a list of hosts:
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/HostDirectivesExamplesTest.java#host1
+
+Making sure the host satisfies the given predicate
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/HostDirectivesExamplesTest.java#host2
+
+Using a regular expressions:
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/HostDirectivesExamplesTest.java#matchAndExtractHost
+
+Beware that in the case of introducing multiple capturing groups in the regex such as in the case bellow, the
+directive will fail at runtime, at the moment the route tree is evaluated for the first time. This might cause
+your http handler actor to enter in a fail/restart loop depending on your supervision strategy.
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/HostDirectivesExamplesTest.java#failing-matchAndExtractHost
+
+

akka-docs-dev/rst/java/http/routing-dsl/directives/host-directives/index.rst

@@ -0,0 +1,15 @@
+.. _HostDirectives-java:
+
+HostDirectives
+==============
+
+HostDirectives allow you to filter requests based on the hostname part of the ``Host`` header
+contained in incoming requests as well as extracting its value for usage in inner routes.
+
+.. toctree::
+   :maxdepth: 1
+
+   host
+   extractHost
+
+   

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

@@ -58,9 +58,13 @@ SchemeDirectives
 WebsocketDirectives
   Contains directives to support answering Websocket requests.
 
+TODO this page should be rewritten as the corresponding Scala page
+
 .. toctree::
   :maxdepth: 1
 
   path-directives
+  method-directives/index
+  host-directives/index
 
 .. _`RFC 7234`: http://tools.ietf.org/html/rfc7234

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/delete.rst

@@ -0,0 +1,17 @@
+.. _-delete-java-:
+
+delete
+======
+
+Matches requests with HTTP method ``DELETE``.
+
+This directive filters an incoming request by its HTTP method. Only requests with
+method ``DELETE`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#delete

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/extractMethod.rst

@@ -0,0 +1,16 @@
+.. _-extractMethod-java-:
+
+extractMethod
+=============
+
+Extracts the :class:`HttpMethod` from the request context and provides it for use for other directives explicitly.
+
+Example
+-------
+
+In the below example our route first matches all ``GET`` requests, and if an incoming request wasn't a ``GET``,
+the matching continues and the extractMethod route will be applied which we can use to programatically
+print what type of request it was - independent of what actual HttpMethod it was:
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#extractMethod
+

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/get.rst

@@ -0,0 +1,17 @@
+.. _-get-java-:
+
+get
+===
+
+Matches requests with HTTP method ``GET``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``GET`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#get

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/head.rst

@@ -0,0 +1,20 @@
+.. _-head-java-:
+
+head
+====
+
+Matches requests with HTTP method ``HEAD``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``HEAD`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+.. note:: By default, akka-http handles HEAD-requests transparently by dispatching a GET-request to the handler and
+   stripping of the result body. See the ``akka.http.server.transparent-head-requests`` setting for how to disable
+   this behavior.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#head

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/index.rst

@@ -0,0 +1,18 @@
+.. _MethodDirectives:
+
+MethodDirectives
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   delete
+   extractMethod
+   get
+   head
+   method
+   options
+   overrideMethodWithParameter
+   patch
+   post
+   put

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/method.rst

@@ -0,0 +1,19 @@
+.. _-method-java-:
+
+method
+======
+
+Matches HTTP requests based on their method.
+
+Description
+-----------
+
+This directive filters the incoming request by its HTTP method. Only requests with
+the specified method are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#method-example

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/options.rst

@@ -0,0 +1,16 @@
+.. _-options-java-:
+
+options
+=======
+
+Matches requests with HTTP method ``OPTIONS``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``OPTIONS`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#options

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/overrideMethodWithParameter.rst

@@ -0,0 +1,11 @@
+.. _-overrideMethodWithParameter-java-:
+
+overrideMethodWithParameter
+===========================
+
+TODO ...
+
+Example
+-------
+
+TODO sample is missing, also in Scala documentation

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/patch.rst

@@ -0,0 +1,17 @@
+.. _-patch-java-:
+
+patch
+=====
+
+Matches requests with HTTP method ``PATCH``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``PATCH`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#patch

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/post.rst

@@ -0,0 +1,17 @@
+.. _-post-java-:
+
+post
+====
+
+Matches requests with HTTP method ``POST``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``POST`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#post

akka-docs-dev/rst/java/http/routing-dsl/directives/method-directives/put.rst

@@ -0,0 +1,16 @@
+.. _-put-java-:
+
+put
+===
+
+Matches requests with HTTP method ``PUT``.
+
+This directive filters the incoming request by its HTTP method. Only requests with
+method ``PUT`` are passed on to the inner route. All others are rejected with a
+``MethodRejection``, which is translated into a ``405 Method Not Allowed`` response
+by the default ``RejectionHandler``.
+
+Example
+-------
+
+.. includecode:: ../../../../code/docs/http/javadsl/server/directives/MethodDirectivesExamplesTest.java#put