Using Reactive Routes

The code presented in this guide is available in this Github repository under the

Before going further, let’s have a look at the HTTP layer of Quarkus.Quarkus HTTP support is based on a non-blocking and reactive engine (Eclipse Vert.x and Netty).All the HTTP requests your application receive are handled by event loops (IO Thread) and then are routed towards the code that manages the request.Depending on the destination, it can invoke the code managing the request on a worker thread (Servlet, Jax-RS) or use the IO Thread (reactive route).Note that because of this, a reactive route must be non-blocking or explicitly declare its blocking nature (which would result by being called on a worker thread).

The first way to use reactive routes is to use the @Route annotation.To have access to this annotation, you need to add the quarkus-vertx-web extension:

In your pom.xml file, add:

Then in a bean, you can use the @Route annotation as follows:

package org.acme.quarkus.sample;
import io.quarkus.vertx.web.Route;
import io.quarkus.vertx.web.RoutingExchange;
import io.vertx.core.http.HttpMethod;
import io.vertx.ext.web.RoutingContext;
import javax.enterprise.context.ApplicationScoped;
@ApplicationScoped
public class MyDeclarativeRoutes {
    @Route(path = "/", methods = HttpMethod.GET)
    public void handle(RoutingContext rc) {
    }
    @Route(path = "/hello", methods = HttpMethod.GET)
    public void greetings(RoutingContext rc) {
        String name = rc.request().getParam("name");
        if (name == null) {
        }
        rc.response().end("hello " + name);
    }
}

The @Route annotation indicates that the method is a reactive route.Again, by default, the code contained in the method must not block.The method gets a RoutingContext as a parameter.From the RoutingContext you can retrieve the HTTP request (using request()) and write the response using response().end(…​).

The @Route annotation allows to configure:

• The path - using the

• The regex - when path is not used.See for more details

• The methods - the HTTP verb triggering the route such as GET, POST…​

• The type - it can be normal (non-blocking), blocking (method dispatched on a worker thread), or failure to indicate that this route is called on failures

• The order - the order of the route when several routes are involved in handling the incoming request.Must be positive for regular user routes.

• The produced and consumed mime types using produces, and consumes

You can also declare several routes for a single method using @Routes:

@Route.Routes({
    @Route(path = "/first"),
    @Route(path = "/second")
    // ...
}

Each route can use different paths, methods…​

You can also register your route directly on the HTTP routing layer by registering routes directly on the Router object.To retrieve the Router instance at startup:

Check the to know more about the route registration, options, and available handlers.

You can also register filters that would intercept incoming HTTP requests.Note that these filters are also applied for servlets, JAX-RS resources, and reactive routes.

For example, the following code snippet registers a filter adding an HTTP header:

package org.acme.quarkus.sample;
import io.quarkus.vertx.http.runtime.filters.Filters;
import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;
@ApplicationScoped
public class MyFilter {
    public void registerMyFilter(@Observes Filters filters) {
        filters.register(rc -> {
            rc.response().putHeader("X-Header", "intercepting the request");
            rc.next();
        }, 100);
    }
}

The registration is done using Filters.register.The first parameter is the handler receiving the .The handler is likely required to call the next() method to continue to chain.The second parameter is the priority used to sort the filters Highest priority are called first.