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 had to be explicitly enabled by configuration in Helidon 2.x:

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.x, HTTP/2 is automatically enabled when an artifact with HTTP/2 support is available in 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

By adding the Helidon WebServer dependency in Helidon 3.x, you can upgrade HTTP/1 to HTTP/2, use without prior knowledge the HTTP/2 Cleartext (H2C) client, and extend HTTP/2 with Application-Layer Protocol Negotiation (ALPN) over TLS.

In Helidon 2.x, max content length was configurable with server.experimental.http2-max-content-length. In Helidon 3.x max content length 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 more information, see 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 a different artifact.

Helidon 2.x WebSocket support dependency
<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-tyrus</artifactId>
</dependency>
Copied
Helidon 3.x WebSocket support dependency
<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-websocket</artifactId>
</dependency>
Copied

In Helidon 2.x, WebSocket routing is defined by registering TyrusSupport as an 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 and API Changes

  • The custom Helidon OCI clients have been deprecated. 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. Use the MultiPart stream readers instead.

Helidon Common

Deprecations in the following classes:

  • Resource - old configuration approach (since 2.0)

    • Method Optional<Resource> create(Config, String) is removed. Use create(Config) instead;

  • ThreadPoolSupplier - Named thread pools (since 2.4.2)

    • Method ThreadPoolSupplier create(Config) is removed. Use create(Config, String) instead;

    • Method ThreadPoolSupplier create() is removed. Use create(String) instead;

Configuration changes:

# old (deprecated approach) - kept so existing applications may work
resources-prefix:
  test-1.resource-path: "src/test/resources/sample.txt"
  test-2.resource-resource-path: "sample.txt"
  test-3.resource-url: "file:./src/test/resources/sample.txt"
  test-4.resource-content-plain: "content"
  test-5.resource-content: "YWJjZGVmZ8SNxZnFvsO6xa8="

# new approach that does not use a prefix
resources:
  test-1.resource.path: "src/test/resources/sample.txt"
  test-2.resource.resource-path: "sample.txt"
Copied

Media Common

Deprecations in the following classes:

  • ContentReaders - Methods with alternatives (since 2.0)

  • ContentTypeCharset - Class with alternative (since 2.0)

  • ContentWriters - Methods with alternatives (since 2.0)

  • MessageBodyReaderContext - Methods with alternatives (since 2.0)

  • MessageBodyWriterContext - Methods with alternatives (since 2.0)

  • ReadableByteChannelPublisher - Class with alternative (since 2.0)

Metrics

Deprecations in the following classes:

  • MetricsSupport - 3 methods, replacing Config with metrics settings

    • Method MetricsSupport create(MetricsSettings, RestServiceSettings) has new parameter;

    • New method MetricsSupport create(MetricsSettings);

    • New method MetricsSupport.Builder<?> builder();

  • KeyPerformanceIndicatorMetricsSettings - new class in metrics API, for backward compatibility only

    • Interface KeyPerformanceIndicatorMetricsSettings - marked for removal;

    • Interface KeyPerformanceIndicatorMetricsSettingsCompatibility - marked for removal;

  • RegistryFactory - New class in metrics API, for backward compatibility only

    • Method RegistryFactory create() - marked for removal;

    • Method RegistryFactory create(Config config) - marked for removal;

    • Method RegistryFactory getInstance() - marked for removal;

    • Method RegistryFactory getInstance(Config config) - marked for removal;

Common Context

Deprecations in the following class:

  • DataPropagationProvider - clearData should use new method

    • Method void clearData() - marked for removal, use void clearData(T data) instead;

GRPC Core

Deprecations:

  • JavaMarshaller - removed support for JavaMarshaller

    • New default marshaller supplier will throw an exception if the code falls to where the JavaMarshaller was returned before to inform developer of the change

LRA

Deprecations in the following class:

  • CoordinatorClient - multiple methods removed

    • Method Single<URI> start(String, long) - removed;

    • Method Single<URI> start(URI, String, long) - removed;

    • Method Single<Optional<URI>> join(URI, long, Participant) - removed;

    • Method Single<Void> cancel(URI) - removed;

    • Method Single<Void> close(URI) - removed;

    • Method Single<Void> leave(URI, Participant) - removed;

    • Method Single<LRAStatus> status(URI) - removed;

  • Headers - class removed

MP Messaging

Deprecations in the following class:

  • FormerHealthProbe - class marked for removal

  • MessagingCdiExtension - Alternative methods used

    • Method Map<String, Boolean> channelsLiveness() - marked for removal;

    • Method Map<String, Boolean> channelsReadiness() - marked for removal;

JWT

Deprecations in the following class:

  • Jwt - Audience can be a list (since 2.4.0)

    • Method Builder audience(String) - removed, use addAudience(String) instead;

MP Metrics

Deprecations in the following class:

  • MetricUtil - multiple methods removed

    • Method public static <E extends Member & AnnotatedElement, A extends Annotation> LookupResult<A> lookupAnnotation(E, Class<? extends Annotation>, Class<?>) - removed;

    • Method <A extends Annotation> LookupResult<A> lookupAnnotation(AnnotatedType<?>, AnnotatedMethod<?>, Class<A>) - removed;

    • Method <E extends Member & AnnotatedElement> void registerMetric(MetricRegistry, E, Class<?>, Annotation, MatchingType) - removed;

    • Method <E extends Member & AnnotatedElement> void registerMetric(E, Class<?>, LookupResult<? extends Annotation>) - removed;

    • Method <E extends Member & AnnotatedElement> void registerMetric(E, Class<?>, Annotation, MatchingType) - removed;

  • Method MetricsCdiExtension - multiple methods removed

    • Method <E extends Member & AnnotatedElement> void registerMetric(E, Class<?>, LookupResult<? extends Annotation>) - removed;

    • Method <E extends Member & AnnotatedElement> void registerMetricInternal(List<RegistrationPrep>, E, Class<?>, LookupResult<? extends Annotation>, Executable) - removed;

    • Method void registerMetricsForAnnotatedSitesFromGrpcTest() - removed;

    • Method recordMetricAnnotatedClass(@Observes @WithAnnotations({Counted.class, Metered.class, Timed.class, ConcurrentGauge.class, SimplyTimed.class, Gauge.class}) ProcessAnnotatedType<?>) - removed;

    • Method <T extends org.eclipse.microprofile.metrics.Metric> MetricType getMetricType(T) - removed;

HTTP Signature Security Provider

  • backwardCompatibleEol - set to false

Service Common

Deprecations in the following class:

  • HelidonRestServiceSupport - method configureEndpoint(Rules) deprecated.

WebServer

  • io.helidon.webserver.staticcontent.* in WebServer - moved to a separate module. Fully removed from WebServer module.