3.x Upgrade

In Helidon 3 we have made some changes to APIs and runtime behavior. This guide will help you upgrade a Helidon SE 2.x application to 3.x.

Java 17 Runtime

Java 11 is no longer supported in Helidon 3. Java 17 or newer is required.

New Routing

Handling routes based on the protocol version is now possible by registering specific routes on routing builder.

For further information check WebServer Documentation

Http/2 Support

Helidon support of Http/2 is no longer experimental.

Http/2 needed to be explicitly enabled by configuration in Helidon 2:

Enabling Http/2 support in Helidon 2:

server:
  port: 8080
  host: 0.0.0.0
  experimental:
    enable-http2: true
    http2-max-content-length: 16384

In Helidon 3 Http/2 is automatically enabled when artifact with Http/2 support is available on the classpath.

Enabling Http/2 support in Helidon 3 by adding dependency:

pom.xml

<dependency>
  <groupId>io.helidon.webserver</groupId>
  <artifactId>helidon-webserver-http2</artifactId>
</dependency>

With above dependency Helidon 3 supports Http/2 upgrade from Http/1, cleartext Http/2 without prior knowledge and Http/2 with ALPN over TLS.

In Helidon 2, max content length was configurable with server.experimental.http2-max-content-length, in Helidon 3 can be configured with server.max-upgrade-content-length globally or per socket with the same max-upgrade-content-length key.

Max upgrade content length in Helidon 3:

server:
  port: 8080
  host: 0.0.0.0
  max-upgrade-content-length: 16384

For further information check WebServer Documentation

WebSocket

Helidon SE support is now based on the WebSocketRouting class which enables Helidon application to configure routing for both annotated and programmatic WebSocket endpoints. TyrusSupport is now deprecated. Websocket support in now placed in different artifact.

Helidon 2 WebSocket support dependency:

pom.xml

<dependency>
  <groupId>io.helidon.webserver</groupId>
  <artifactId>helidon-webserver-tyrus</artifactId>
</dependency>

Helidon 3 WebSocket support dependency:

pom.xml

<dependency>
  <groupId>io.helidon.webserver</groupId>
  <artifactId>helidon-webserver-websocket</artifactId>
</dependency>

In Helidon 2, WebSocket routing is defined by registering TyrusSupport as additional service:

Helidon 2 WebSocket route registering:

WebServer.builder(Routing.builder()
    .register("/rest", new SomeRestService())1
    .register("/websocket", TyrusSupport.builder()2
        .register(ServerEndpointConfig.Builder
            .create(MessageBoardEndpoint.class, "/")
            .encoders(encoders)
            .build())
        .build()
    ))
    .port(8080)
    .build();

Traditional REST routing service registration
WebSocket setup with Tyrus service

In Helidon 3, WebSocket routing is defined by adding another routing:

Helidon 3 WebSocket route registering:

WebServer.builder()
    .routing(r -> r
        .register("/rest", new SomeRestService()))1
    .addRouting(WebSocketRouting.builder()2
        .endpoint("/websocket", ServerEndpointConfig.Builder
            .create(MessageBoardEndpoint.class, "/board")
            .encoders(encoders)
            .build())
        .build())
    .port(8080)

Traditional REST routing service registration
WebSocket routing setup

Deprecations

The custom Helidon OCI clients have been deprecated (see PR).

Use the OCI Java SDK instead. For Helidon MP, use io.helidon.integrations.oci:helidon-integrations-oci only for OCI authentication, region, and configuration support; the legacy io.helidon.integrations.oci.sdk:helidon-integrations-oci-sdk-cdi module is deprecated.

The MultiPart buffered readers have been deprecated (see PR). Use the MultiPart stream readers instead.