or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdhttp-routing.mdhttp-services.mdhttp1-protocol.mdindex.mdrequest-response.mdserver-management.mdspi.md
tile.json

tessl/maven-io-helidon-webserver--helidon-webserver

High-performance HTTP server implementation built on Java 21 Virtual Threads for Helidon microservices framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.helidon.webserver/helidon-webserver@4.2.x

To install, run

npx @tessl/cli install tessl/maven-io-helidon-webserver--helidon-webserver@4.2.0

index.mddocs/

Helidon WebServer

Helidon WebServer is a modern, high-performance HTTP server implementation that leverages Java 21 Virtual Threads to provide excellent throughput with thread-per-request simplicity. It serves as the core web server component of the Helidon microservices framework, supporting both Helidon SE (functional style) and Helidon MP (MicroProfile) programming models.

Package Information

  • Package Name: helidon-webserver
  • Package Type: maven
  • Language: Java
  • Group ID: io.helidon.webserver
  • Artifact ID: helidon-webserver
  • Version: 4.2.2
  • Installation: Add to Maven pom.xml:
<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver</artifactId>
    <version>4.2.2</version>
</dependency>

Core Imports

import io.helidon.webserver.WebServer;
import io.helidon.webserver.WebServerConfig;
import io.helidon.webserver.http.HttpRouting;
import io.helidon.webserver.http.Handler;
import io.helidon.webserver.http.ServerRequest;
import io.helidon.webserver.http.ServerResponse;

Basic Usage

import io.helidon.webserver.WebServer;
import io.helidon.webserver.http.HttpRouting;

public class HelloWorldServer {
    public static void main(String[] args) {
        // Create HTTP routing
        HttpRouting routing = HttpRouting.builder()
            .get("/hello", (req, res) -> res.send("Hello World!"))
            .get("/users/{id}", (req, res) -> {
                String userId = req.path().pathParameters().get("id");
                res.send("User ID: " + userId);
            })
            .post("/users", (req, res) -> {
                // Handle user creation
                res.status(201).send("User created");
            })
            .build();

        // Create and start the server
        WebServer server = WebServer.builder()
            .routing(routing)
            .port(8080)
            .build()
            .start();

        System.out.println("Server started at: http://localhost:" + server.port());
    }
}

Architecture

Helidon WebServer is built around several key components:

  • WebServer: The main server interface that manages listeners and lifecycles
  • Router: Generic routing system supporting multiple protocols (HTTP, WebSocket, etc.)
  • HTTP Routing: HTTP-specific routing with method-based handlers and filters
  • Virtual Thread Support: Built-in support for Java 21 Virtual Threads for high concurrency
  • Protocol Abstraction: Extensible architecture supporting HTTP/1.1, HTTP/2, and custom protocols
  • Service Provider Interface (SPI): Extensibility points for custom features and protocols

Capabilities

Server Management

Core server lifecycle management, configuration, and listener control. Essential for creating and managing HTTP servers with multiple protocols and configurations.

interface WebServer extends RuntimeType.Api<WebServerConfig> {
    static WebServer create(WebServerConfig serverConfig);
    static WebServer create(Consumer<WebServerConfig.Builder> builderConsumer);
    static WebServerConfig.Builder builder();
    
    WebServer start();
    WebServer stop();
    boolean isRunning();
    int port();
    int port(String socketName);
    boolean hasTls();
    boolean hasTls(String socketName);
    void reloadTls(Tls tls);
    void reloadTls(String socketName, Tls tls);
    Context context();
}

Server Management

HTTP Routing

HTTP-specific routing system with method-based handlers, filters, and comprehensive request/response processing. Supports RESTful APIs, middleware, and error handling.

interface HttpRouting extends Routing, Prototype.Api {
    static Builder builder();
    static HttpRouting create();
    static HttpRouting empty();
    
    void route(ConnectionContext ctx, RoutingRequest request, RoutingResponse response);
    HttpSecurity security();
    Class<? extends Routing> routingType();
}

interface HttpRouting.Builder extends HttpRules, io.helidon.common.Builder<Builder, HttpRouting> {
    Builder register(HttpService... service);
    Builder register(String path, HttpService... service);
    Builder route(HttpRoute route);
    Builder get(String pathPattern, Handler... handlers);
    Builder post(String pathPattern, Handler... handlers);
    Builder put(String pathPattern, Handler... handlers);
    Builder delete(String pathPattern, Handler... handlers);
    Builder addFilter(Filter filter);
    Builder addFeature(HttpFeature feature);
    <T extends Throwable> Builder error(Class<T> exceptionClass, ErrorHandler<? super T> handler);
}

HTTP Routing

Request and Response Handling

Complete HTTP request and response interfaces with entity handling, headers, parameters, and content negotiation.

interface ServerRequest extends HttpRequest {
    // Request interface methods
}

interface ServerResponse {
    // Response interface methods  
}

interface Handler {
    void handle(ServerRequest req, ServerResponse res);
    
    static Handler create(Consumer<ServerRequest> handler);
    static Handler create(Function<ServerRequest, ?> handler);
    static Handler create(Supplier<?> handler);
}

Request and Response Handling

HTTP Services and Features

Modular service system for creating reusable HTTP components, middleware, and features that can be registered with routing.

interface HttpService {
    void routing(HttpRules rules);
}

interface HttpFeature {
    void setup(HttpRouting.Builder routing);
}

interface Filter {
    void filter(FilterChain chain, RoutingRequest req, RoutingResponse res);
}

interface ErrorHandler<T extends Throwable> {
    void handle(ServerRequest req, ServerResponse res, T throwable);
}

HTTP Services and Features

Configuration

Type-safe configuration system using builder patterns and Blueprint annotations for all server components.

interface WebServerConfig extends Prototype.Api {
    static Builder builder();
    // Configuration methods
}

interface ListenerConfig extends Prototype.Api {
    static Builder builder();
    // Listener configuration methods
}

interface ConnectionConfig extends Prototype.Api {
    static Builder builder();
    // Connection configuration methods
}

Configuration

HTTP/1.1 Protocol Implementation

Complete HTTP/1.1 protocol implementation with connection management, request parsing, and response generation.

interface Http1Config extends Prototype.Api {
    static Builder builder();
    // HTTP/1.1 specific configuration
}

class Http1Connection implements ServerConnection {
    // HTTP/1.1 connection implementation
}

class Http1ServerRequest implements ServerRequest {
    // HTTP/1.1 request implementation
}

class Http1ServerResponse implements ServerResponse {
    // HTTP/1.1 response implementation
}

HTTP/1.1 Protocol

Service Provider Interface (SPI)

Extension points for custom protocols, features, and connection handling. Enables third-party integrations and custom server functionality.

interface ServerFeature {
    // Server feature SPI
}

interface ProtocolConfigProvider {
    // Protocol configuration provider SPI
}

interface ServerConnectionSelectorProvider {
    // Connection selector provider SPI
}

interface SinkProvider {
    // Streaming response provider SPI
}

Service Provider Interface

Common Types

interface Routing {
    Class<? extends Routing> routingType();
}

interface Route {
    // Base route interface
}

interface ConnectionContext {
    // Connection context interface
}

class CloseConnectionException extends RuntimeException {
    // Exception to close connections
}

class ServerConnectionException extends RuntimeException {
    // Server connection related exceptions
}

Error Handling

Helidon WebServer provides comprehensive error handling through:

  • ErrorHandler<T>: Type-safe exception handlers for specific exception types
  • Global error handlers: Default error handling for unhandled exceptions
  • HTTP status mapping: Automatic HTTP status code assignment based on exception types
  • Custom error responses: Full control over error response format and content