Helidon MP 3.x Upgrade Guide

In Helidon 3.x we have made some changes to APIs and runtime behavior. This guide will help you upgrade a Helidon MP 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.

javax namespace to jakarta namespace

Helidon 3 supports MicroProfile 5.0 and selected Jakarta EE 9.1 APIs. In Jakarta EE 9.1 the Java package namespace was changed from javax to jakarta. Therefore, you must change your application to use jakarta instead of corresponding javax for Jakarta EE packages.

In version 3.x Helidon supports MicroProfile 5.0 specification, which now is fully migrated to jakarta namespace.

As a result, javax module is no longer in dependency management of Helidon parent pom files.

MicroProfile 5.0 Support

MicroProfile 5.0 enables MicroProfile APIs to be used together with Jakarta EE 9.1 (Jakarta EE namespace). This release was mainly focused on updating dependencies from javax to jakarta, as well as overall stability and usability improvements.

MicroProfile 5.0 lays the foundation for the rapid innovation of MicroProfile APIs for its 2022 releases.

MicroProfile 5.0 is an umbrella for the following specifications and their corresponding versions:

  • MicroProfile Config 3.0.1

  • MicroProfile Fault Tolerance 4.0

  • MicroProfile Health 4.0

  • MicroProfile JWT Authentication 2.0

  • MicroProfile Metrics 4.0

  • MicroProfile OpenAPI 3.0

  • MicroProfile OpenTracing 3.0

  • MicroProfile Rest Client 3.0

Helidon 3.x supports the following Jakarta EE specifications:

  • CDI (Jakarta Contexts and Dependency Injection) 3.0

  • JAX-RS (Jakarta RESTful Web Services) 3.0

  • JSON-B (Jakarta JSON Binding) 2.0

  • JSON-P (Jakarta JSON Processing) 2.0.1

  • Jakarta Annotations 2.0

  • Jakarta Persistence API 3.0

  • Jakarta Transactions API 2.0

  • Jakarta WebSocket API 2.0

  • Jakarta Bean Validation 2.0

Helidon code was modified to support the corresponding specification’s versions.

Incompatible changes for each specification

The migration from javax to jakarta namespace makes this release backward incompatible with previous versions of MicroProfile. For each specification there are also API and functional changes that are described below.

MicroProfile specifications

Supported Jakarta EE specifications

Before you migrate to Helidon 3.x, make sure that you have read each specification for a complete list of incompatible changes.

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.