=doc document java-side handlers

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

@@ -0,0 +1,88 @@
+.. _handlers-java:
+
+Handlers
+========
+
+Handlers implement the actual application-defined logic for a certain trace in the routing tree. Most of the leaves of
+the routing tree will be routes created from handlers. Creating a ``Route`` from a handler is achieved using the
+``BasicDirectives.handleWith`` overloads. They come in several forms:
+
+ * with a single ``Handler`` argument
+ * with a number ``n`` of ``RequestVal<T1>`` arguments and a ``HandlerN<T1, .., TN>`` argument
+ * with a ``Class<?>`` and/or instance and a method name String argument and a variable number of ``RequestVal<?>``
+   arguments
+
+Simple Handler
+--------------
+
+In its simplest form a ``Handler`` is a SAM class that defines application behavior
+by inspecting the ``RequestContext`` and returning a ``RouteResult``:
+
+.. includecode:: /../../akka-http/src/main/scala/akka/http/javadsl/server/Handler.scala
+   :include: handler
+
+Such a handler inspects the ``RequestContext`` it receives and uses the ``RequestContext``'s methods to
+create a response:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: simple-handler
+
+The handler can include any kind of logic but must return a ``RouteResult`` in the end which can only
+be created by using one of the ``RequestContext`` methods.
+
+A handler instance can be used once or several times as shown in the full example:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: simple-handler-example-full
+
+Handlers and Request Values
+---------------------------
+
+In many cases, instead of manually inspecting the request, a handler will make use of :ref:`request-vals-java`
+to extract details from the request. This is possible using one of the other ``handleWith`` overloads that bind
+the values of one or more request values with a ``HandlerN`` instance to produce a ``Route``:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: handler2
+
+The handler here implements multiplication of two integers. However, it doesn't need to specify where these
+parameters come from. In ``handleWith``, as many request values of the matching type have to be specified as the
+handler needs. This can be seen in the full example:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: handler2-example-full
+
+Here, the handler is again being reused. First, in creating a route that expects URI parameters ``x`` and ``y``. This
+route is then used in the route structure. And second, the handler is used with another set of ``RequestVal`` in the
+route structure, this time representing segments from the URI path.
+
+Handlers in Java 8
+------------------
+
+In Java 8 handlers can be provided as function literals. The example from before then looks like this:
+
+.. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleSpec.java
+   :include: handler2-example-full
+
+
+Providing Handlers by Reflection
+--------------------------------
+
+Using Java before Java 8, writing out handlers as (anonymous) classes can be unwieldy. Therefore, ``handleWith``
+overloads are provided that allow writing handler as simple methods and specifying them by name:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: reflective
+
+The complete calculator example can then be written like this:
+
+.. includecode:: ../../code/docs/http/javadsl/HandlerExampleSpec.java
+  :include: reflective-example-full
+
+There are alternative overloads for ``handleWith`` that take a ``Class`` instead of an object instance to refer to
+static methods. The referenced method must be publicly accessible.
+
+Deferring Result Creation
+-------------------------
+
+TODO

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

@@ -12,3 +12,6 @@ High-level Server-Side API
    routes
    directives/index
    request-vals/index
+   handlers
+   path-matchers
+   marshalling

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

@@ -0,0 +1,6 @@
+.. _marshalling-java:
+
+Marshalling & Unmarshalling
+===========================
+
+TODO

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

@@ -56,6 +56,12 @@ fields, details of the request like headers, URI, the entity, or authentication
 
 Read more about :ref:`request-vals-java`.
 
+The actual application-defined processing of a request is defined with a ``Handler`` instance or by specifying
+a handling method with reflection. A handler can receive the value of any request values and is converted into
+a ``Route`` by using one of the ``BasicDirectives.handleWith`` directives.
+
+Read more about :ref:`handlers-java`.
+
 Requests or responses often contain data that needs to be interpreted or rendered in some way.
 Akka-http provides the abstraction of ``Marshaller`` and ``Unmarshaller`` that define how domain model objects map
 to HTTP entities.

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

@@ -0,0 +1,6 @@
+.. _pathmatcher-dsl-java:
+
+The PathMatcher DSL
+===================
+
+TODO