Helidon SE 3.x Upgrade Guide

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. Please follow the instructions in Prerequisites for proper installation.

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

yaml

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

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

yaml

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

xml

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

Helidon 3 WebSocket support dependency

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

java

WebServer.builder(Routing.builder()
                          .register("/rest", new SomeRestService()) 
                          .register("/websocket", TyrusSupport.builder() 
                                  .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

java

WebServer.builder()
        .routing(r -> r
                .register("/rest", new SomeRestService()) 
        )
        .addRouting(WebSocketRouting.builder() 
                            .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.

NOTE

See Resolving compatibility issue with OCI SDK for detailed information on how to work around this issue.

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