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

.. _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 and a variable number of ``RequestVal<?>`` (may be 0)
* 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<?>`` (may be 0)
  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:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.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:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.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:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.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:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.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
------------------

Handlers are in fact simply classes which extend ``akka.japi.function.FunctionN`` in order to make reasoning
about the number of handled arguments easier. For example, a :class:`Handler1[String]` is simply a
``Function2[RequestContext, String, RouteResult]``. You can think of handlers as hot-dogs, where each ``T``
type represents a sausage, put between the "buns" which are ``RequestContext`` and ``RouteResult``.

In Java 8 handlers can be provided as function literals or method references. The example from before then looks like this:

.. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.java
   :include: handler2-java8-example-full


.. note::
  The reason the ``handleWith##`` methods include the number of handled values is because otherwise (if overloading would
  be used, for all 22 methods) error messages generated by ``javac`` end up being very long and not readable, i.e.
  if one type of a handler does not match the given values, *all* possible candidates would be printed in the error message
  (22 of them), instead of just the one arity-matching method, pointing out that the type does not match.

   We opted for better error messages as we feel this is more helpful when developing applications,
   instead of having one overloaded method which looks nice when everything works, but procudes hard to read error
   messages if something does not match up.



Providing Handlers by Reflection
--------------------------------

Using Java before Java 8, writing out handlers as (anonymous) classes can be unwieldy. Therefore, ``handleReflectively``
overloads are provided that allow writing handler as simple methods and specifying them by name:

.. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.java
  :include: reflective

The complete calculator example can then be written like this:

.. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleDocTest.java
  :include: reflective-example-full

There are alternative overloads for ``handleReflectively`` 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