Chapter 1. Migrating applications to Red Hat build of Quarkus 3.8

You can no longer use the previous configuration names stork."service-name".load-balancer and quarkus.stork."service-name".load-balancer for configuring the Stork load balancer. Instead, use quarkus.stork."service-name".load-balancer.type for configuration settings.

OkHttp and Okio have been removed from the Quarkus Platform BOM, and their versions are no longer enforced, addressing issues related to outdated dependencies. This change affects test framework dependencies and streamlines runtime dependencies. Developers using these dependencies must now specify their versions in build files. Additionally, the quarkus-test-infinispan-client artifact has been removed due to the availability of robust Dev Services support for Infinispan.

Beginning with this version of Red Hat build of Quarkus, support for Java 11, deprecated in the previous version, has been removed. Java 21 is now the recommended version, although Java 17 is also supported.

In Red Hat build of Quarkus, using RESTEasy Reactive with Java Architecture for XML Binding (JAXB) does not support using collections, arrays, and maps as parameters or return types in REST methods. To overcome this limitation of JAXB, encapsulate these types within a class annotated with @XmlRootElement.

During the static initialization phase, Red Hat build of Quarkus collects the configuration to inject in CDI beans. The collected values are then compared with their runtime initialization counterparts, and if a mismatch is detected, the application startup fails. With Red Hat build of Quarkus 3.8, you can now annotate configuration objects with the @io.quarkus.runtime.annotations.StaticInitSafe annotation to inform users that the injected configuration:

User tags in templates are now executed in isolation by default, restricting access to the calling template’s context. This update can alter data handling within tag templates, potentially impacting their current functionality. To bypass this isolation and maintain access to the parent context, include _isolated=false or _unisolated in the tag call, for example, # itemDetail item showImage=true _isolated=false. This approach allows tags to access data from the parent context as before. This change minimizes unintended data exposure from the parent context to the tag, enhancing template data integrity. However, it might necessitate updates to existing templates reliant on shared context access, representing a notable change that could affect users unfamiliar with this isolation mechanism.

ResultNode class is updated to be an abstract class, not an interface, and should not be user-implemented despite being in the public API. The Qute API now limits CompletionStage implementations to java.util.concurrent.CompletableFuture and io.quarkus.qute.CompletedStage by default, a restriction alterable with -Dquarkus.qute.unrestricted-completion-stage-support=true.

With Red Hat build of Quarkus 3.8, the following quarkus-rest-client extensions are renamed:

The @TestHTTPResource annotation now supports path parameters. Validation as a URI string is no longer applied due to non-compliance with the URI format.

The GraalVM SDK version has been updated to 23.1.2 in Red Hat build of Quarkus 3.8. Developers using extensions requiring GraalVM substitutions should switch from org.graalvm.sdk:graal-sdk to org.graalvm.sdk:nativeimage to access necessary classes. For those that use org.graalvm.js:js, replace this dependency with org.graalvm.polyglot:js-community for the community version. For the enterprise version, replace this dependency with org.graalvm.polyglot:js. The adjustment for the graal-sdk is automated with quarkus update. However, changes to the js dependency must be made manually. Even though it is highly unlikely, this change could affect users who depend on:

In this release, QuarkusComponentTest has undergone several adjustments. It remains experimental and is not supported by Red Hat build of Quarkus. This experimental status indicates that the API might change at any time, reflecting feedback received.

The QuarkusComponentTestExtension is now immutable, requiring programmatic registration through the simplified constructor QuarkusComponentTestExtension(Class…) or the QuarkusComponentTestExtension.builder() method. The test instance lifecycle, either Lifecycle#PER_METHOD (default) or Lifecycle#PER_CLASS, dictates when the CDI container starts and stops; PER_METHOD starts the container before each test and stops it afterward, whereas PER_CLASS starts it before all tests and stops it after all tests. This represents a change from previous versions, where the container always started before and stopped after all tests.

In Red Hat build of Quarkus 3.8, Hibernate Object-Relational Mapping (ORM) was upgraded to version 6.4 and introduced the following breaking changes:

For more information, see the Hibernate ORM 6.4 migration guide.

When using Hibernate ORM on Red Hat build of Quarkus 3.8, you can verify the specified database version on application startup.

For Hibernate ORM to generate more efficient SQL and take advantage of more database features, you can set a specific database version for the Hibernate database in the applications.properties file.

For example: quarkus.datasource.db-version = 14.0

With this 3.8 release, on application startup, Red Hat build of Quarkus verifies the specified database version against the actual database version your application is connecting to, and throws an exception on startup in case of a mismatch.

For more information, see the Supported databases section of the Quarkus "Using Hibernate ORM and Jakarta persistence" guide.

In Red Hat build of Quarkus 3.8, Hibernate Search was upgraded to version 7.0 and introduced the following breaking changes:

For more information, see the following resources:

Dev Services for SQL Server updated its default image from mcr.microsoft.com/mssql/server:2019-latest to mcr.microsoft.com/mssql/server:2022-latest.

Users preferring the previous version can specify an alternative by using the config property detailed in the References section in the Red Hat build of Quarkus "Configure data sources" guide.

In Red Hat build of Quarkus 3.8, the Flyway extension is upgraded to Flyway 9.20.0, which delivers an additional dependency, flyway-database-oracle, for Oracle users.

Oracle users must update the pom.xml file to include the flyway-database-oracle dependency. To do so, do the following:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-oracle</artifactId>
</dependency>

For more information, see the Quarkus Using Flyway guide.

The Kafka extension’s Strimzi OAuth support in quarkus-bom now uses io.strimzi:strimzi-kafka-oauth version 0.14.0, introducing a known issue that leads to native build failures. The error, Substitution target for `io.smallrye.reactive.kafka.graal.Target_com_jayway_jsonpath_internal_DefaultsImpl is not loaded can be bypassed by adding io.strimzi:kafka-oauth-common to your project’s classpath.

When using Opentelemetry (oTel) instrumentation with Red Hat build of Quarkus 3.8, you can now annotate a method in any Context Dependency Injection (CDI)-aware bean by using the io.opentelemetry.instrumentation.annotations.AddingSpanAttributes annotation, which does not create a new span but adds annotated method parameters to attributes in the current span.

For more information, see the CDI section of the Quarkus "Using OpenTelemetry" guide.

With Red Hat build of Quarkus 3.8, the quarkus-smallrye-metrics extension is no longer supported. Now, it is available as a community extension only. Its use in production environments is discouraged.

From Red Hat build of Quarkus 3.8, quarkus-smallrye-metrics is replaced by the fully supported quarkus-micrometer extension.

With Red Hat build of Quarkus 3.8, SmallRye OpenTracing is no longer supported. To continue using distributed tracing, migrate your applications to SmallRye OpenTelemetry, which is now fully supported with this release and no longer a Technology Preview feature. If you still need to use quarkus-smallrye-opentracing, adjust your application to use the extensions from Quarkiverse by updating the groupId and specifying the version manually.

In Red Hat build of Quarkus 3.8, integration of OpenTelemetry Tracing and the quarkus-scheduler extension has been refactored.

Before this update, only @Scheduled methods had a new io.opentelemetry.api.trace.Span class, which is associated automatically when you enable tracing. That is, when the quarkus.scheduler.tracing.enabled configuration property is set to true, and the quarkus-opentelemetry extension is available.

With this 3.8 release, all scheduled jobs, including those that are scheduled programmatically, have a Span associated automatically when tracing is enabled. The unique job identifier for each scheduled method is either generated, is specified by setting the io.quarkus.scheduler.Scheduled#identity attribute or with the JobDefinition method. Before this update, span names followed the <simpleclassname>.<methodName> format.

For more information, see the following Quarkus resources:

When mTLS client authentication (quarkus.http.ssl.client-auth) is set to required, Red Hat build of Quarkus automatically disables plain HTTP ports to ensure that only secure HTTPS requests are accepted. To enable plain HTTP, configure quarkus.http.ssl.client-auth to request or set both quarkus.http.ssl.client-auth=required and quarkus.http.insecure-requests=enabled.

The JWT extension no longer transitively depends on the Reactive Routes extension. If your application uses both JWT and Reactive Routes features but does not declare an explicit dependency on Reactive Routes, you must add this dependency.

The quarkus-keycloak-authorization extension no longer includes the org.keycloak:keycloak-adapter-core dependency due to its update to Keycloak 22.0.0 and its irrelevance to the extension’s functionality. In future Keycloak versions, it is planned to remove the Keycloak Java adapters code. If your application requires this dependency, manually add it to your project’s pom.xml.

You can no longer use Context and Dependency Injection (CDI) annotations and interceptors to resolve tenant OIDC configuration for RESTEasy Classic applications.

Due to security checks that are enforced before CDI interceptors and checks requiring authentication are triggered, using CDI interceptors to resolve multiple OIDC provider configuration identifiers no longer works.

Use @Tenant annotation or custom io.quarkus.oidc.TenantResolver instead.

For more information, see the Resolve with annotations section of the Quarkus "Using OIDC multitenancy guide".

In Red Hat build of Quarkus 3.8, you must now use the quarkus.oidc.TenantFeature annotation instead of quarkus.oidc.Tenant to bind OpenID Connect (OIDC) features to OIDC tenants.

The quarkus.oidc.Tenant annotation is now used for resolving tenant configuration.

Red Hat build of Quarkus 3.8 allows runtime configuration of HTTP permissions and roles, enabling flexible security settings across profiles. This resolves the issue of native executables locking to build-time security configurations. Security can now be dynamically adjusted per profile, applicable in both JVM and native modes.

The application of annotation-based GraphQL directives has been corrected to ensure they are only applied to the schema element types for which they are declared.

For example, if a directive was declared to apply to the GraphQL element type FIELD but was erroneously applied to a different element type, it was still visible in the schema on the element where it should not be applicable, leading to an invalid schema. This was now corrected, and directives have their usage checked against their applicability declaration.

If you had directives applied incorrectly in this way, they will no longer appear in the schema, and Red Hat build of Quarkus 3.8 will log a warning during the build.

Red Hat build of Quarkus 3.8 has enhanced its REST Client’s Server-Sent Events (SSE) capabilities, enabling complete event returns and filtering. These updates and new descriptions in REST Client provide developers with increased control and flexibility in managing real-time data streams.

Until version 3.8, the Red Hat build of Quarkus SmallRye JWT automatically incorporated quarkus-reactive-routes, a feature discontinued from version 3.8 onwards. To ensure continued functionality, manually add quarkus-reactive-routes as a dependency in your build configuration.