+doc,htc #18600,18597 documents where/how to deal with failure in Http

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

@@ -6,10 +6,10 @@ Directives
 A directive is a wrapper for a route or a list of alternative routes that adds one or more of the following
 functionality to its nested route(s):
 
- * it filters the request and lets only matching requests pass (e.g. the `get` directive lets only GET-requests pass)
- * it modifies the request or the ``RequestContext`` (e.g. the `path` directives filters on the unmatched path and then
-   passes an updated ``RequestContext`` unmatched path)
- * it modifies the response coming out of the nested route
+* it filters the request and lets only matching requests pass (e.g. the `get` directive lets only GET-requests pass)
+* it modifies the request or the ``RequestContext`` (e.g. the `path` directives filters on the unmatched path and then
+  passes an updated ``RequestContext`` unmatched path)
+* it modifies the response coming out of the nested route
 
 akka-http provides a set of predefined directives for various tasks. You can access them by either extending from
 ``akka.http.javadsl.server.AllDirectives`` or by importing them statically with
@@ -46,7 +46,7 @@ MethodDirectives
 MiscDirectives
   Contains directives that validate a request by user-defined logic.
 
-:ref:`PathDirectives-java`
+:ref:`path-directives-java`
   Contains directives to match and filter on the URI path of the incoming request.
 
 RangeDirectives

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

@@ -1,4 +1,4 @@
-.. _PathDirectives-java:
+.. _path-directives-java:
 
 PathDirectives
 ==============

akka-docs-dev/rst/java/http/routing-dsl/overview.rst

@@ -74,3 +74,27 @@ quickly without running them over the network and helps with writing assertions
 Read more about :ref:`http-testkit-java`.
 
 .. _DRY: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+
+.. _handling-http-server-failures-high-level-scala:
+
+Handling HTTP Server failures in the High-Level API
+---------------------------------------------------
+There are various situations when failure may occur while initialising or running an Akka HTTP server.
+Akka by default will log all these failures, however sometimes one may want to react to failures in addition
+to them just being logged, for example by shutting down the actor system, or notifying some external monitoring
+end-point explicitly.
+
+Bind failures
+^^^^^^^^^^^^^
+For example the server might be unable to bind to the given port. For example when the port
+is already taken by another application, or if the port is privileged (i.e. only usable by ``root``).
+In this case the "binding future" will fail immediatly, and we can react to if by listening on the Future's completion:
+
+.. includecode:: ../../code/docs/http/javadsl/server/HighLevelServerBindFailureExample.java
+  :include: binding-failure-high-level-example
+
+
+.. note::
+  For a more low-level overview of the kinds of failures that can happen and also more fine-grained control over them
+  refer to the :ref:`handling-http-server-failures-low-level-java` documentation.
+