///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Request Handling
:description: Helidon Reactive WebServer request handling
:keywords: helidon, reactive, reactive streams, reactive java, reactive webserver

== Request Handling

Implement the logic to handle requests to WebServer in a `Handler`, which is a `FunctionalInterface`.
 Handlers:

 * Process the request and <<anchor-sending-response,send>> a response.
 * Act as a filter and forward requests to downstream handlers using the `request.next()`
 method.
 * Throw an exception or call `request.next(exception)` to begin
 <<webserver/05_error-handling.adoc,error handling>>.

=== Process Request and Produce Response
Each `Handler` has two parameters. `ServerRequest` and `ServerResponse`.

* Request provides access to the request method, URI, path, query parameters,
 headers and entity.
* Response provides an ability to set response code, headers, and entity.

[[anchor-filtering]]
=== Handler as a Filter
The handler forwards the request to the downstream handlers by
 _nexting_. There are two options:

* call `req.next()`
+
[source,java]
----
.any("/hello", (req, res) -> { // <1>
    // filtering logic  // <2>
    req.next(); // <3>
})
----
<1> handler for any HTTP method using the `/hello` path
<2> business logic implementation
<3> forward the current request to the downstream handler

* call `req.next(throwable)` to forward the handling to the
 <<webserver/05_error-handling.adoc,error handlers>>
+
[source,java]
----
.any("/hello", (req, res) -> { // <1>
    // filtering logic (e.g., validating parameters) // <2>
    if (userParametersOk()) {
        req.next(); // <3>
    } else {
        req.next(new IllegalArgumentException("Invalid parameters."); // <4>
    }
})
----
<1> handler for any HTTP method using the `/hello` path
<2> custom logic 
<3> forward the current request to the downstream handler
<4> forward the request to the error handler

The handling logic can explicitly forward the execution to a different thread. 
This is the reason why returning from the handler can't automatically
 trigger calling the next handler.

[[anchor-sending-response]]
=== Sending a response
To complete the request handling, you must send a response by calling the `res.send()` method.

[source,java]
----
.get("/hello", (req, res) -> { // <1>
    // terminating logic
    res.status(Http.Status.ACCEPTED_201);
    res.send("Saved!"); // <2>
})
----
<1> handler that terminates the request handling for any HTTP method using the `/hello` path 
<2> send the response
