Helidon SE 3.x Upgrade Guide

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

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

Copied

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

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

Copied

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

Copied

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

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

Copied

Helidon 3 WebSocket support dependency

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

Copied

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()) 
                          .register("/websocket", TyrusSupport.builder() 
                                  .register(ServerEndpointConfig.Builder
                                                    .create(MessageBoardEndpoint.class, "/")
                                                    .encoders(encoders)
                                                    .build())
                                  .build()
                          ))
        .port(8080)
        .build();

Copied

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()) 
        )
        .addRouting(WebSocketRouting.builder() 
                            .endpoint("/websocket", ServerEndpointConfig.Builder
                                    .create(MessageBoardEndpoint.class, "/board")
                                    .encoders(encoders)
                                    .build())
                            .build())
        .port(8080)

Copied

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. If you use Helidon MP you can inject OCI SDK clients by adding the dependency io.helidon.integrations.oci.sdk:helidon-integrations-oci-sdk-cdi.

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.