or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdparameter-injection.mdreactive-streaming.mdrequest-context.mdrequest-filtering.mdroute-declaration.md
tile.json

tessl/maven-io-quarkus--quarkus-reactive-routes

REST framework offering the route model to define non blocking endpoints

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-reactive-routes@3.26.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-reactive-routes@3.26.0

index.mddocs/

Quarkus Reactive Routes

Quarkus Reactive Routes is a REST framework offering a declarative route model to define non-blocking endpoints as an alternative to traditional JAX-RS resources. It provides annotation-driven HTTP endpoint creation with comprehensive support for reactive programming patterns, parameter injection, request filtering, and streaming responses.

Package Information

  • Package Name: quarkus-reactive-routes
  • Package Type: maven
  • Group ID: io.quarkus
  • Artifact ID: quarkus-reactive-routes
  • Language: Java
  • Installation: Add to your Quarkus project's pom.xml:
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-reactive-routes</artifactId>
</dependency>

Core Imports

import io.quarkus.vertx.web.Route;
import io.quarkus.vertx.web.Route.HttpMethod;
import io.quarkus.vertx.web.RouteBase;
import io.quarkus.vertx.web.Param;
import io.quarkus.vertx.web.Header;
import io.quarkus.vertx.web.Body;
import io.quarkus.vertx.web.RoutingExchange;

Basic Usage

import io.quarkus.vertx.web.Route;
import io.quarkus.vertx.web.Route.HttpMethod;
import io.quarkus.vertx.web.Param;
import io.quarkus.vertx.web.RoutingExchange;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class UserRoutes {

    @Route(path = "/users", methods = HttpMethod.GET)
    public String listUsers() {
        return "List of users";
    }

    @Route(path = "/users/:id", methods = HttpMethod.GET)
    public String getUser(@Param("id") String userId, RoutingExchange exchange) {
        return "User: " + userId;
    }

    @Route(path = "/users", methods = HttpMethod.POST, consumes = "application/json")
    public String createUser(@Body User user) {
        return "Created user: " + user.getName();
    }
}

Architecture

Quarkus Reactive Routes is built around several key components:

  • Annotation-Driven Routes: @Route and related annotations for declarative endpoint definition
  • Parameter Injection: Automatic extraction of request parameters, headers, and body content
  • Reactive Responses: Full support for Uni<T> and Multi<T> return types for asynchronous processing
  • Request Filtering: @RouteFilter for implementing cross-cutting concerns
  • Streaming Support: Built-in support for Server-Sent Events, JSON streaming, and NDJSON
  • Context Access: RoutingExchange interface providing comprehensive request/response manipulation

Capabilities

Route Declaration

Core functionality for defining HTTP endpoints using declarative annotations. Supports path-based and regex-based routing with comprehensive HTTP method and content-type configuration.

@Route(
    path = "/api/users/:id",
    methods = HttpMethod.GET,
    produces = "application/json",
    consumes = "application/json",
    type = Route.HandlerType.NORMAL,
    order = 100
)
public String handleRequest() { return "response"; }

@RouteBase(
    path = "/api/v1",
    produces = {"application/json"},
    consumes = {"application/json"}
)
public @interface RouteBase {
    String path() default "";
    String[] produces() default {};
    String[] consumes() default {};
}

Route Declaration

Parameter Injection

System for extracting request data including path parameters, query parameters, HTTP headers, and request body content with automatic type conversion and validation support.

public String handleRequest(
    @Param("id") String userId,
    @Param("limit") Optional<String> limit,
    @Header("Authorization") String authHeader,
    @Body User userData
) { return "processed"; }

Parameter Injection

Request Context and Exchange

Comprehensive interface for accessing and manipulating HTTP request and response objects, providing both low-level Vert.x access and high-level convenience methods.

public interface RoutingExchange {
    io.vertx.ext.web.RoutingContext context();
    io.vertx.core.http.HttpServerRequest request();
    io.vertx.core.http.HttpServerResponse response();
    Optional<String> getParam(String name);
    Optional<String> getHeader(CharSequence name);
    io.vertx.core.http.HttpServerResponse ok();
    void ok(String chunk);
    io.vertx.core.http.HttpServerResponse serverError();
    io.vertx.core.http.HttpServerResponse notFound();
}

Request Context

Reactive Streaming

Support for reactive response types including Uni<T> for single asynchronous values and Multi<T> for streaming data with built-in content-type handling for Server-Sent Events, JSON arrays, and NDJSON.

@Route(path = "/stream", produces = ReactiveRoutes.EVENT_STREAM)
public Multi<String> streamEvents() { return Multi.createFrom().items("event1", "event2"); }

public class ReactiveRoutes {
    public static final String APPLICATION_JSON = "application/json";
    public static final String EVENT_STREAM = "text/event-stream";
    public static final String ND_JSON = "application/x-ndjson";
    public static final String JSON_STREAM = "application/stream+json";
}

Reactive Streaming

Request Filtering

Cross-cutting concern implementation using @RouteFilter annotation for handling authentication, logging, request modification, and other concerns that apply across multiple endpoints.

@RouteFilter(priority = 10)
public void authenticate(RoutingExchange exchange) {
    // Filter logic
}

Request Filtering

Types

public enum Route.HttpMethod {
    GET, HEAD, POST, PUT, DELETE, OPTIONS
}

public enum Route.HandlerType {
    NORMAL, BLOCKING, FAILURE;
    public static HandlerType from(String value);
}

public interface ReactiveRoutes.ServerSentEvent<T> {
    default String event() { return null; }
    T data();
    default long id() { return -1L; }
}