CtrlK
BlogDocsLog inGet started
Tessl Logo

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

REST framework offering the route model to define non blocking endpoints

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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; }
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-reactive-routes@3.26.x
Publish Source
CLI
Badge
tessl/maven-io-quarkus--quarkus-reactive-routes badge