mp.guides.upgrade_3x.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2022, 2023 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Helidon MP 3.x Upgrade Guide
:description: Helidon MP 3.x Upgrade Guide
:keywords: helidon, porting, migration, upgrade, incompatibilities, 3.x
:rootdir: {docdir}/../..
include::{rootdir}/includes/mp.adoc[]
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 xref:{rootdir}/about/prerequisites.adoc[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 {version-lib-microprofile-config}
* MicroProfile Fault Tolerance {version-lib-microprofile-fault-tolerance-api}
* MicroProfile Health {version-lib-microprofile-health}
* MicroProfile JWT Authentication {version-lib-microprofile-jwt}
* MicroProfile Metrics {version-lib-microprofile-metrics-api}
* MicroProfile OpenAPI {version-lib-microprofile-openapi-api}
* MicroProfile OpenTracing {version-lib-microprofile-tracing}
* MicroProfile Rest Client {version-lib-microprofile-rest-client}
Helidon 3.x supports the following Jakarta EE specifications:
* CDI (Jakarta Contexts and Dependency Injection) {version-lib-jakarta-cdi}
* JAX-RS (Jakarta RESTful Web Services) {version-lib-jakarta-jaxrs-api}
* JSON-B (Jakarta JSON Binding) {version-lib-jakarta-jsonb-api}
* JSON-P (Jakarta JSON Processing) {version-lib-jakarta-jsonp-api}
* Jakarta Annotations {version-lib-jakarta-annotations-api}
* Jakarta Persistence API {version-lib-jakarta-persistence-api}
* Jakarta Transactions API {version-lib-jakarta-transaction-api}
* Jakarta WebSocket API {version-lib-jakarta-websockets-api}
* Jakarta Bean Validation {version-lib-jakarta-bean-validation}
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 {version-lib-microprofile-config}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-config-3.0.1/microprofile-config-spec-3.0.1.html#_incompatible_changes[MicroProfile Config {version-lib-microprofile-config} Specification]
* *MicroProfile Fault Tolerance {version-lib-microprofile-fault-tolerance-api}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-fault-tolerance-4.0/microprofile-fault-tolerance-spec-4.0.html#_backward_incompatible_changes=[MicroProfile Fault Tolerance {version-lib-microprofile-fault-tolerance-api} Specification]
* *MicroProfile Health {version-lib-microprofile-health}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-health-4.0/microprofile-health-spec-4.0.html#_incompatible_changes[MicroProfile Health {version-lib-microprofile-health} Specification]
* *MicroProfile JWT Authentication {version-lib-microprofile-jwt}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-jwt-auth-2.0/microprofile-jwt-auth-spec-2.0.html#_incompatible_changes[MicroProfile JWT Authentication {version-lib-microprofile-jwt} Specification]
* *MicroProfile Metrics {version-lib-microprofile-metrics-api}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-metrics-4.0/microprofile-metrics-spec-4.0.html#_incompatible_changes[MicroProfile Metrics {version-lib-microprofile-metrics-api} Specification]
* *MicroProfile OpenAPI {version-lib-microprofile-openapi-api}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-open-api-2.0.1/microprofile-openapi-spec-2.0.1.html#_incompatible_changes[MicroProfile OpenAPI {version-lib-microprofile-openapi-api} Specification]
* *MicroProfile OpenTracing {version-lib-microprofile-tracing}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-opentracing-3.0/microprofile-opentracing-spec-3.0.html#_incompatible_changes[MicroProfile OpenTracing {version-lib-microprofile-tracing} Specification]
* *MicroProfile Rest Client {version-lib-microprofile-rest-client}*:
+
Incompatible changes described in link:https://download.eclipse.org/microprofile/microprofile-rest-client-3.0/microprofile-rest-client-spec-3.0.html#_incompatible_changes[MicroProfile Rest Client {version-lib-microprofile-rest-client} Specification]
=== Supported Jakarta EE specifications
* *CDI (Jakarta Contexts and Dependency Injection) {version-lib-jakarta-cdi}*:
+
Changes described in link:https://jakarta.ee/specifications/cdi/3.0/jakarta-cdi-spec-3.0.html#architecture[CDI (Jakarta Contexts and Dependency Injection) {version-lib-jakarta-cdi} Specification]
* *JAX-RS (Jakarta RESTful Web Services) {version-lib-jakarta-jaxrs-api}*:
+
Moved to `jakarta` namespace. Changes described in link:https://download.eclipse.org/microprofile/microprofile-rest-client-3.0/microprofile-rest-client-spec-3.0.html#_incompatible_changes[JAX-RS (Jakarta RESTful Web Services) {version-lib-jakarta-jaxrs-api}Specification]
* *JSON-B (Jakarta JSON Binding) {version-lib-jakarta-jsonb-api}*:
+
Moved to `jakarta` namespace. Changes described in link:https://jakarta.ee/specifications/jsonb/2.0/jakarta-jsonb-spec-2.0.html#change-log[JSON-B (Jakarta JSON Binding) {version-lib-jakarta-jsonb-api} Specification]
* *JSON-P (Jakarta JSON Processing) {version-lib-jakarta-jsonp-api}*:
+
Moved to `jakarta` namespace.
* *Jakarta Annotations {version-lib-jakarta-annotations-api}*:
+
Moved to `jakarta` namespace. Moved to `jakarta` namespace. Full information in link:https://jakarta.ee/specifications/annotations/2.0/annotations-spec-2.0.html[Jakarta Annotations {version-lib-jakarta-annotations-api} Specification]
* *Jakarta Persistence API {version-lib-jakarta-persistence-api}*:
+
Moved to `jakarta` namespace. Changes described in link:https://jakarta.ee/specifications/persistence/3.0/jakarta-persistence-spec-3.0.html#revision-history[Jakarta Persistence API {version-lib-jakarta-persistence-api} Specification]
* *Jakarta Transactions API {version-lib-jakarta-transaction-api}*:
+
Moved to `jakarta` namespace. Changes described in link:https://jakarta.ee/specifications/transactions/2.0/jakarta-transactions-spec-2.0.html#revision-history[Jakarta Transactions API {version-lib-jakarta-transaction-api} Specification]
* *Jakarta WebSocket API {version-lib-jakarta-websockets-api}*:
+
Moved to `jakarta` namespace. Changes described in link:https://jakarta.ee/specifications/websocket/2.0/websocket-spec-2.0.html#changes[Jakarta WebSocket API {version-lib-jakarta-websockets-api} Specification]
* *Jakarta Bean Validation {version-lib-jakarta-bean-validation}*:
+
Moved to `jakarta` namespace. Changes described in link:https://jakarta.ee/specifications/bean-validation/2.0/bean-validation_2.0.html#changelog[Jakarta Bean Validation {version-lib-jakarta-bean-validation} Specification]
NOTE: Please, read each specification carefully for incompatible changes!
== Deprecations
- 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`.
NOTE: See xref:{rootdir}/mp/integrations/oci.adoc#oci-compatibility[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)
* `ThreadPoolSupplier` - Named thread pools (since 2.4.2)
More information in the following link:https://github.com/oracle/helidon/issues/4363[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 link:https://github.com/oracle/helidon/issues/4364[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 link:https://github.com/oracle/helidon/issues/4365[Task].
=== Common Context
Deprecations in the following class:
* `DataPropagationProvider` - clearData should use new method
More information in the following link:https://github.com/oracle/helidon/issues/4366[Task].
=== GRPC core
Deprecations:
* `JavaMarshaller` - removed support for JavaMarshaller
More information in the following link:https://github.com/oracle/helidon/issues/4367[Task].
=== LRA
Deprecations in the following class:
* `CoordinatorClient` - multiple methods
* `Headers`
More information in the following link:https://github.com/oracle/helidon/issues/4368[Task].
=== MP Messaging
Deprecations in the following class:
* `MessagingCdiExtension` - Alternative methods used
More information in the following link:https://github.com/oracle/helidon/issues/4369[Task].
=== JWT
Deprecations in the following class:
* `Jwt` - Audience can be a list (since 2.4.0)
More information in the following link:https://github.com/oracle/helidon/issues/4370[Task].
=== MP Metrics
Deprecations in the following class:
* `MetricUtil` - multiple methods
* `MetricsCdiExtension` - multiple methods
More information in the following link:https://github.com/oracle/helidon/issues/4371[Task].
=== HTTP Signature Security Provider
* `backwardCompatibleEol` - set to false
More information in the following link:https://github.com/oracle/helidon/issues/4372[Task].
=== Service Common
Deprecations in the following class:
* `HelidonRestServiceSupport` - method _configureEndpoint(Rules)_
More information in the following link:https://github.com/oracle/helidon/issues/4371[Task].
=== WebServer
* `Static content support` in `WebServer` - moved to a separate module. Fully removed from `WebServer` module.
More information in the following link:https://github.com/oracle/helidon/issues/4374[Task].
© 2015 - 2025 Weber Informatics LLC | Privacy Policy