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

With Red Hat build of Quarkus 3.15, the quarkus-spring-data-rest-extension was upgraded to align with the latest Spring Boot 3 API updates.

If you use the PagingAndSortingRepository interface in your code, this upgrade might introduce breaking changes. Previously, the PagingAndSortingRepository extended the CrudRepository, which allowed your custom repository to inherit the methods from the CrudRepository.

To resolve any issues related to this change, you must update your custom repository to extend either ListCrudRepository or CrudRepository directly. This adjustment ensures continued access to the required methods and maintains compatibility with the updated architecture.

In Red Hat build of Quarkus 3.15, the method for determining whether Dev Services should start has changed.

Previously, to decide whether to start Dev Services, Red Hat build of Quarkus checked if a configuration property was defined without expanding it. However, this approach caused issues if the property expanded to an empty value.

Now, Red Hat build of Quarkus first checks whether the expanded property is empty. This change might result in Dev Services starting unexpectedly where they didn’t before, in cases when the expanded property ends up being empty. Most Dev Services start when a given property is not provided, for instance, the JDBC URL.

Due to this change, you should adjust your configuration properties to include a default value, ensuring that the expanded property is not empty.

For example, if you use the quarkus-test-oidc-server component to mock the OpenID Connect (OIDC) server, and your application.properties file contains:

%test.quarkus.oidc.auth-server-url=${keycloak.url}/realms/quarkus/

%test.quarkus.oidc.auth-server-url=${keycloak.url}/realms/quarkus/

Change the property value to:

%test.quarkus.oidc.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus/

%test.quarkus.oidc.auth-server-url=${keycloak.url:replaced-by-test-resource}/realms/quarkus/

This way, if keycloak.url is not defined, the default replaced-by-test-resource value prevents the property from expanding to an empty value, thereby avoiding the unintended startup of Dev Services. If a variable is not defined in an expression, the whole expression will be empty.

Red Hat build of Quarkus 3.15 updates the GraalVM SDK dependencies to version 23.1.2, correcting an earlier oversight and ensuring compatibility with the latest GraalVM features.

If you develop extensions with GraalVM substitutions, replace the org.graalvm.sdk:graal-sdk dependency with org.graalvm.sdk:nativeimage. The nativeimage artifact includes only the required classes for substitutions, making it more streamlined.

You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the Infinispan 15 component is upgraded to version 15.0.

In earlier releases, before Infinispan 15 integration, you ran queries by using the following .Query.java code:

@Inject
RemoteCache<String, Book> booksCache;

…

QueryFactory queryFactory = Search.getQueryFactory(booksCache);
Query query = queryFactory.create("from book_sample.Book");
List<Book> list = query.execute().list();

@Inject
RemoteCache<String, Book> booksCache;

…

QueryFactory queryFactory = Search.getQueryFactory(booksCache);
Query query = queryFactory.create("from book_sample.Book");
List<Book> list = query.execute().list();

However, with this release, this code no longer works because RemoteCache is now an @ApplicationScoped proxy bean and Search.getQueryFactory raises a ClassCastException.

To resolve this, remove the indirection by using the query method in the RemoteCache API as follows:

@Inject
RemoteCache<String, Book> booksCache;

…

Query<Book> query = booksCache.<Book>query("from book_sample.Book");
List<Book> list = query.execute().list();

@Inject
RemoteCache<String, Book> booksCache;

…

Query<Book> query = booksCache.<Book>query("from book_sample.Book");
List<Book> list = query.execute().list();

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the following packaging-related properties have been renamed or changed. If you use the original properties in your configuration, they still work, but a warning is displayed.

You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

Update any code and configuration files to reflect these changes and stop warning messages during the build process.

In Red Hat build of Quarkus 3.15, the deprecated ProfileManager class and ProfileManager#getActiveProfile method are removed because the ProfileManager did not handle multiple profiles.

With this removal, the following configuration change is required:

To retrieve an active profile, use the io.quarkus.runtime.configuration.ConfigUtils#getProfiles API.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In earlier releases, an unintended behavior was observed where a quarkus-app directory was always generated in the build system’s output directory, regardless of the type of artifact produced.

In Red Hat build of Quarkus 3.15, the build process creates the quarkus-app directory only for fast-jar packages, which is the default artifact type. If you configure the build for a different artifact type, the quarkus-app directory is not created.

In Red Hat build of Quarkus 3.15, the extension annotation processor used to generate runtime files and configuration documentation has been redeveloped, offering more flexibility but with new constraints:

Moving to the new @ConfigMapping interface is encouraged, but support for legacy @ConfigRoot classes is planned to continue for a while to ensure a smooth migration. Deprecation plans are planned to be announced at a later date.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

With Red Hat build of Quarkus 3.15, the Hibernate ORM extension verifies that the database version it connects to at runtime is at least as high as the one configured at build time. This verification occurs even when the configuration relies on default settings targeting the minimum database versions supported by Red Hat build of Quarkus.

This update aims to alert application developers aware if they try to use a database version that Hibernate ORM or Red Hat build of Quarkus no longer support. If you try to use a database version that is no longer supported, Red Hat build of Quarkus does not start and throws an exception.

This change affects applications that rely on the following database versions:

If you cannot upgrade the database to a supported version, you can still try to use it, although some features might not work. To continue using an earlier, unsupported database version, set the db-version explicitly and, if necessary, set the dialect also.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

For more information, see the following resources:

In Red Hat build of Quarkus 3.15, the default images for several Dev Services have been updated to the following versions:

You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

To use a specific version or distribution of these services, you must manually override the default container image in your application properties.

For more information, see the Configuring the image section of the Quarkus "Dev Services for Elasticsearch" guide.

In Red Hat build of Quarkus 3.15, the Hibernate Object/Relational Mapping (ORM) auto-flush feature is optimized.

Now, by default, before running a Hibernate Query Language (HQL), Java Persistence Query Language (JPQL), or native query, Hibernate ORM flushes only pending changes to the database if it detects that these changes might impact the query results.

In most cases, this optimization will improve the performance of your applications, such as with more efficient batching, however, the following issues might occur:

If you want to revert to previous behavior and choose an alternative default value, the quarkus.hibernate-orm.flush.mode configuration property is introduced. Set this property to always: quarkus.hibernate-orm.flush.mode=always.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

For more information, see the following resources:

In Red Hat build of Quarkus 3.15, Hibernate ORM extensions were upgraded to Hibernate ORM 6.6 and introduced the following breaking changes:

For more information, see the following resources:

The quarkus-hibernate-search-orm-outbox-polling extension relies on system tables in the database to which Hibernate ORM connects, and with Red Hat build of Quarkus 3.15, the schema of these system tables might change.

If you use this extension, you need to migrate your database schema. For information about how to migrate your database schema, see the Outbox polling database tables section in the "Hibernate Search migration" guide.

If you cannot update your database schema, apply the following settings to restore the previous defaults:

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the io.quarkus:quarkus-panache-common annotation processor has been removed because it is no longer required for externally defined entities when using Hibernate ORM with Panache, Hibernate Reactive with Panache, or MongoDB with Panache.

In earlier releases, this annotation processor was automatically run when found in the classpath. If you had overridden the set of annotation processors in your build tool, you needed to add it explicitly.

Remove all references to io.quarkus:quarkus-panache-common from the annotation processor list.

You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

<build>
    <plugins>
        <!-- other plugins -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.quarkus</groupId>
                        <artifactId>quarkus-panache-common</artifactId>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        <!-- other plugins -->
    </plugins>
</build>

<build>
    <plugins>
        <!-- other plugins -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>io.quarkus</groupId>
                        <artifactId>quarkus-panache-common</artifactId>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        <!-- other plugins -->
    </plugins>
</build>

dependencies {
    annotationProcessor "io.quarkus:quarkus-panache-common"
}

dependencies {
    annotationProcessor "io.quarkus:quarkus-panache-common"
}

In Red Hat build of Quarkus 3.15, the execution mode for synchronous methods in Quarkus Messaging extensions now defaults to worker threads. In earlier versions, these methods ran on the Vert.x event loop (I/O thread).

For example, the following processing method is now called by default on a worker thread instead of the Vert.x I/O thread:

package org.acme;

import org.eclipse.microprofile.reactive.messaging.Incoming;
import org.eclipse.microprofile.reactive.messaging.Outgoing;

@Incoming("source")
@Outgoing("sink")
public Result process(int payload) {
    return new Result(payload);
}

package org.acme;

import org.eclipse.microprofile.reactive.messaging.Incoming;
import org.eclipse.microprofile.reactive.messaging.Outgoing;

@Incoming("source")
@Outgoing("sink")
public Result process(int payload) {
    return new Result(payload);
}

To revert to the earlier behavior, you can use the quarkus.messaging.blocking.signatures.execution.mode configuration property.

Possible values are:

You can also adjust the execution mode on a per-method basis by using the @Blocking and @NonBlocking annotations:

package org.acme;

import io.smallrye.common.annotation.NonBlocking;
import org.eclipse.microprofile.reactive.messaging.Incoming;

@Incoming("source")
@NonBlocking
public void consume(int payload) {
    // called on I/O thread
}

package org.acme;

import io.smallrye.common.annotation.NonBlocking;
import org.eclipse.microprofile.reactive.messaging.Incoming;

@Incoming("source")
@NonBlocking
public void consume(int payload) {
    // called on I/O thread
}

By annotating the method with @NonBlocking, you ensure it is called on the Vert.x event loop (I/O thread).

Review your messaging methods to ensure they run in the required execution mode, and update your code or configuration as needed.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the SmallRye Reactive Messaging extensions have been renamed to quarkus-messaging-* to reflect their support for both reactive and blocking workloads.

Maven relocations have been implemented. You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

Replace all instances of the old extension names in your projects with the new names.

The configuration root has also been updated from quarkus.smallrye-reactive-messaging. to quarkus.messaging.. An automatic fallback mechanism is in place to revert to the old configuration properties, if necessary.

Update your code and configurations to reflect these changes.

In Red Hat build of Quarkus 3.15, all configuration properties under the quarkus.opentelemetry.* namespace have been removed.

These properties were deprecated and maintained for backward compatibility in versions 3.2 and 3.8. Because they are now removed in 3.15, you must make the following changes to migrate your applications:

Update your code and configurations to use these new properties and values.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the deprecated annotation io.opentelemetry.extension.annotations.WithSpan has been removed. Update your code to use the new io.opentelemetry.instrumentation.annotations.WithSpan annotation.

Review and change any configurations or code that rely on the old annotation to ensure compatibility with this update.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the OpenTelemetry (OTel) SDK has been upgraded to version 1.39.0 and instrumentation to version 2.5.0. This upgrade enforces the new conventions defined in the OpenTelemetry HTTP semantic convention stability migration. It also completes the removal of the deprecated standards. Update any code or configurations that depend on those conventions.

Additionally, the quarkus.otel.semconv-stability.opt-in system property has been removed because opting-in is no longer supported. Update any code or configurations that depend on this property.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the OpenTelemetry (OTel) REST client span names now include both the HTTP request method and path; for example, GET /hello. Earlier REST client span names included only the HTTP method.

Update any code or configurations that depend on the specific format of REST client span names.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the span names generated by database operations have changed due to updates in the libraries we use.

For example, before this change, the old span name for creating a database table was DB Query. Now, with this change, the new span name is CREATE TABLE {table_name}.

This new naming convention provides more descriptive and meaningful span names that accurately reflect the specific database operations performed.

As a result, you might notice different names for spans generated by database operations in your observability tools.

Review and update any custom monitoring configurations, alerts, or dashboards that rely on the old span names to accommodate the new naming convention.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

For more information about the database span naming conventions and best practices, see the OpenTelemetry Database Span Semantic Conventions specification.

In earlier versions, some configuration properties were incorrectly located under the quarkus.health configuration root.

In Red Hat build of Quarkus 3.15, those properties have relocated to the quarkus.smallrye-health configuration root for consistency:

In Red Hat build of Quarkus 3.15, the properties with the old configuration roots have been deprecated and are planned to be removed in a future release. Update any code or configurations to use the new property locations.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

With Red Hat build of Quarkus 3.15, Java Keystroke (JKS) is no longer the default keystore and truststore format.

Instead, Red Hat build of Quarkus determines the format based on the file extension, as follows:

If your file does not use one of these extensions, you must set the file format.

For example, to specify the JKS format, set the following configuration values:

In Red Hat build of Quarkus 3.15, the quarkus.oidc.authentication.user-info-required property is now automatically set to true when io.quarkus.oidc.UserInfo is injected into a REST endpoint. This change removes the need to configure this property manually, because UserInfo is typically injected when its use is intended.

However, in more complex setups where multiple OIDC tenants secure endpoints, and some tenants do not support UserInfo, this change might lead to tenant initialization failures. This happens only when a tenant that does not support UserInfo is still configured to acquire it, potentially causing requests secured by that tenant to fail.

To avoid such failures in multi-tenant setups, set the tenant-specific quarkus.oidc.<tenant-id>.authentication.user-info-required property to false for tenants that do not support UserInfo. This ensures that only tenants that support UserInfo enforce its acquisition.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the Quarkus BOM no longer enforces the version of the org.junit-pioneer:junit-pioneer dependency. If you are using this dependency in your project, you must explicitly specify its version in your build files.

To avoid any build issues, define the version in your pom.xml or build.gradle files; for example:

<properties>
    ...
    <junit-pioneer.version>2.2.0</junit-pioneer.version>
    ...
</properties>

<properties>
    ...
    <junit-pioneer.version>2.2.0</junit-pioneer.version>
    ...
</properties>

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, for Quarkus REST (formerly RESTEasy Reactive), the signatures of the Hypertext Application Language (HAL) wrapper classes have been modified to include the type of elements in the collection:

Add the appropriate type argument wherever you use the HAL wrapper classes in your code.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

@Path("/records")
public class RecordsResource {

    @Inject
    HalService halService;

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @RestLink(rel = "list")
    public HalCollectionWrapper<Record> getAll() {
        List<Record> list = // ...
        HalCollectionWrapper<Record> halCollection = halService.toHalCollectionWrapper( list, "collectionName", Record.class);
        // ...
        return halCollection;
    }

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @Path("/{id}")
    @RestLink(rel = "self")
    @InjectRestLinks(RestLinkType.INSTANCE)
    public HalEntityWrapper<Record> get(@PathParam("id") int id) {
        Record entity = // ...
        HalEntityWrapper<Record> halEntity = halService.toHalWrapper(entity);
        // ...
        return halEntity;
    }
}

@Path("/records")
public class RecordsResource {

    @Inject
    HalService halService;

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @RestLink(rel = "list")
    public HalCollectionWrapper<Record> getAll() {
        List<Record> list = // ...
        HalCollectionWrapper<Record> halCollection = halService.toHalCollectionWrapper( list, "collectionName", Record.class);
        // ...
        return halCollection;
    }

    @GET
    @Produces({ MediaType.APPLICATION_JSON, RestMediaType.APPLICATION_HAL_JSON })
    @Path("/{id}")
    @RestLink(rel = "self")
    @InjectRestLinks(RestLinkType.INSTANCE)
    public HalEntityWrapper<Record> get(@PathParam("id") int id) {
        Record entity = // ...
        HalEntityWrapper<Record> halEntity = halService.toHalWrapper(entity);
        // ...
        return halEntity;
    }
}

Although creating HAL wrappers by using constructors still works, that approach might be deprecated in a future version. Therefore, start using the helper methods exposed by the HalService bean.

For more information, see the Web Links support section of the "Quarkus REST" guide.

In earlier releases, Quarkus REST (formerly RESTEasy Reactive) filters ran even when the requested resource was not a REST resource. In Red Hat build of Quarkus 3.15, that behavior has changed. Now, Quarkus REST filters run only on REST resources.

If you need your filters to apply to non-Quarkus REST resources, you can do so by adding a custom ExceptionMapper for NotFoundException, as shown in the following example:

package io.quarkus.resteasy.reactive.server.test.customproviders;

import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class NotFoundExeptionMapper implements ExceptionMapper<NotFoundException> {
    @Override
    public Response toResponse(NotFoundException exception) {
        return Response.status(404).build();
    }
}

package io.quarkus.resteasy.reactive.server.test.customproviders;

import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;

@Provider
public class NotFoundExeptionMapper implements ExceptionMapper<NotFoundException> {
    @Override
    public Response toResponse(NotFoundException exception) {
        return Response.status(404).build();
    }
}

With this ExceptionMapper, Quarkus REST handles "Not Found" resources, allowing filters to run as expected. Earlier, filters always ran on non-REST resources, which made it difficult for other extensions to handle "Not Found" scenarios effectively.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the io.quarkus.qute.TemplateInstance class is no longer registered as a non-blocking type. As a result, if a Jakarta REST (formerly JAX-RS) resource method returns a TemplateInstance object, it is now considered blocking by default.

To restore the earlier non-blocking behavior, apply the @io.smallrye.common.annotation.NonBlocking annotation to the resource method.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

In Red Hat build of Quarkus 3.15, the RESTEasy Reactive extensions have been renamed to quarkus-rest-* to reflect their support for both reactive and blocking workloads.

Maven relocations have been implemented. You can apply this change by running the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

Replace all instances of the old extension names in your projects with the new names.

Most of the new extension names follow this naming convention:

The configuration roots have also been updated:

An automatic fallback mechanism is in place to revert to the old configuration properties if necessary.

In Red Hat build of Quarkus 3.15, the quarkus-webjars-locator extension is renamed to quarkus-web-dependency-locator and is also enhanced to include mvnpm(Maven NPM) and importmaps.

Update your code and configurations to use the new extension name.

You must apply this change manually. It is not covered by the automated update described in the Migrating applications to Red Hat build of Quarkus 3.15 guide.

For more information, see the Quarkus Web dependency locator guide.