88 lines
3.6 KiB
ReStructuredText
88 lines
3.6 KiB
ReStructuredText
|
.. _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
|