3.x Upgrade

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.

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.1
• MicroProfile Fault Tolerance 4.0.2
• MicroProfile Health 4.0
• MicroProfile JWT Authentication 2.1
• MicroProfile Metrics 5.1.1
• MicroProfile OpenAPI 3.1.1
• MicroProfile OpenTracing 3.0
• MicroProfile Rest Client 3.0

Helidon 3.x supports the following Jakarta EE specifications:

• CDI (Jakarta Contexts and Dependency Injection) 4.0
• JAX-RS (Jakarta RESTful Web Services) 3.1
• JSON-B (Jakarta JSON Binding) 3.0
• JSON-P (Jakarta JSON Processing) 2.1
• Jakarta Annotations 2.1.1
• Jakarta Persistence API 3.1
• Jakarta Transactions API 2.0
• Jakarta WebSocket API 2.1
• Jakarta Bean Validation 3.0

Corresponding changes to Helidon code were made to support the corresponding specifications' versions.

Incompatible changes for each specification

Migration from javax to jakarta namespace is making this release backward incompatible with previous version of MicroProfile. For each specification there are also API and functional changes, described below.

MicroProfile specifications

• MicroProfile Config 3.1:
  Incompatible changes described in MicroProfile Config 3.1 Specification
• MicroProfile Fault Tolerance 4.0.2:
  Incompatible changes described in MicroProfile Fault Tolerance 4.0.2 Specification
• MicroProfile Health 4.0:
  Incompatible changes described in MicroProfile Health 4.0 Specification
• MicroProfile JWT Authentication 2.1:
  Incompatible changes described in MicroProfile JWT Authentication 2.1 Specification
• MicroProfile Metrics 5.1.1:
  Incompatible changes described in MicroProfile Metrics 5.1.1 Specification
• MicroProfile OpenAPI 3.1.1:
  Incompatible changes described in MicroProfile OpenAPI 3.1.1 Specification
• MicroProfile OpenTracing 3.0:
  Incompatible changes described in MicroProfile OpenTracing 3.0 Specification
• MicroProfile Rest Client 3.0:
  Incompatible changes described in MicroProfile Rest Client 3.0 Specification

Supported Jakarta EE specifications

• CDI (Jakarta Contexts and Dependency Injection) 4.0:
  Changes described in CDI (Jakarta Contexts and Dependency Injection) 4.0 Specification
• JAX-RS (Jakarta RESTful Web Services) 3.1:
  Moved to jakarta namespace. Changes described in JAX-RS (Jakarta RESTful Web Services) 3.1Specification
• JSON-B (Jakarta JSON Binding) 3.0:
  Moved to jakarta namespace. Changes described in JSON-B (Jakarta JSON Binding) 3.0 Specification
• JSON-P (Jakarta JSON Processing) 2.1:
  Moved to jakarta namespace.
• Jakarta Annotations 2.1.1:
  Moved to jakarta namespace. Moved to jakarta namespace. Full information in Jakarta Annotations 2.1.1 Specification
• Jakarta Persistence API 3.1:
  Moved to jakarta namespace. Changes described in Jakarta Persistence API 3.1 Specification
• Jakarta Transactions API 2.0:
  Moved to jakarta namespace. Changes described in Jakarta Transactions API 2.0 Specification
• Jakarta WebSocket API 2.1:
  Moved to jakarta namespace. Changes described in Jakarta WebSocket API 2.1 Specification
• Jakarta Bean Validation 3.0:
  Moved to jakarta namespace. Changes described in Jakarta Bean Validation 3.0 Specification

Deprecations

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

Helidon Common

Deprecations in the following classes:

• Resource - old configuration approach (since 2.0)
• ThreadPoolSupplier - Named thread pools (since 2.4.2)

More information in the following task.

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)

More information in the following task.

Metrics

Deprecations in the following classes:

• MetricsSupport - 3 methods, replacing Config with metrics settings
• KeyPerformanceIndicatorMetricsSettings - New class in metrics API, for backward compatibility only
• RegistryFactory - New class in metrics API, for backward compatibility only

More information in the following task.

Common Context

Deprecations in the following class:

• DataPropagationProvider - clearData should use new method

More information in the following task.

GRPC core

Deprecations:

• JavaMarshaller - removed support for JavaMarshaller

More information in the following task.

LRA

Deprecations in the following class:

• CoordinatorClient - multiple methods
• Headers

More information in the following task.

MP Messaging

Deprecations in the following class:

• MessagingCdiExtension - Alternative methods used

More information in the following task.

JWT

Deprecations in the following class:

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

More information in the following task.

MP Metrics

Deprecations in the following class:

• MetricUtil - multiple methods
• MetricsCdiExtension - multiple methods

More information in the following task.

HTTP Signature Security Provider

• backwardCompatibleEol - set to false

More information in the following task.

Service Common

Deprecations in the following class:

• HelidonRestServiceSupport - method configureEndpoint(Rules)

More information in the following task.

WebServer

• Static content support in WebServer - moved to a separate module. Fully removed from WebServer module.

More information in the following task.