Skip to content

Migration Guide 3.9

Jump to bottom
Clement Escoffier edited this page Mar 4, 2024 · 35 revisions
Note

We highly recommend the use of quarkus update to update to a new version of Quarkus.

Items marked below with ⚙️ ✅ are automatically handled by quarkus update.

Panache annotation processor removed for Hibernate ORM/Hibernate Reactive/MongoDB

For externally defined entities, in Hibernate ORM with Panache, Hibernate Reactive with Panache, and MongoDB with Panache, we used to require to run the io.quarkus:quarkus-panache-common annotation processor, which would be automatic when found in the classpath, except in case you overrode the set of annotation processors to run in your build tool, in which case you had to add the annotation processor explicitly in your build tool.

With Quarkus 3.9, this is no longer required, and the annotation processor has been removed, so you should remove all usage of the io.quarkus:quarkus-panache-common annotation processor from your build files.

For Maven builds, this would be located here:

<build>
    <plugins>
        [...]
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.12.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>
        [...]
    </plugins>
</build>

For Gradle, this would be located here:

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

OpenTelemetry

Current Semantic Conventions for HTTP will soon change and the current conventions are deprecated for removal soon.

Please move to the new conventions by setting the new property quarkus.otel.semconv-stability.opt-in to http for the new conventions or http/dup to produce duplicated old and new conventions attributes.

Please check the OpenTelemetry extension configuration reference for more details and full set of changes at the HTTP semantic convention stability migration guide from OpenTelemetry.

RESTEasy Reactive: Adding web links programmatically

The HAL wrappers class signatures have been updated to include the type of elements in the collection as listed below.

  • HalCollectionWrapper<T>

  • HalEntityWrapper<T>

You should add the type argument everywhere you use the HAL wrapper classes.

The preferred way of creating the wrapper classes changed from using the constructor to use helper methods exposed on the io.quarkus.hal.HalService bean as shown below:

@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;
    }
}

Creating the wrappers using the constructors will still work for now, but this might change in the future.

Elasticsearch/OpenSearch

Dev Services

The Elasticsearch/OpenSearch Dev Services now default to starting:

  • Elasticsearch 8.12, instead of 8.9 previously

  • OpenSearch 2.11, instead of 2.9 previously

To force the use of a specific distribution (Elasticsearch vs. OpenSearch) or version, configure the container image explicitly.

Hibernate Search

Database schema changed for outbox-polling system tables

The Quarkus extension for Hibernate Search with outbox-polling relies on system tables in your database, and with Quarkus 3.9 the schema of these system tables may need to change.

See this section of the Hibernate Search migration guide for information on how to migrate your database schema if you were using that extension.

If you cannot update your database schema at the moment, you can use the following settings to restore previous defaults:

  • For the default persistence unit: 

    quarkus.hibernate-search-orm.coordination.entity-mapping.agent.uuid-type=char
quarkus.hibernate-search-orm.coordination.entity-mapping.outbox-event.uuid-type=char

  • For named persistence units: 

    quarkus.hibernate-search-orm."persistence-unit-name".coordination.entity-mapping.agent.uuid-type=char
quarkus.hibernate-search-orm."persistence-unit-name".coordination.entity-mapping.outbox-event.uuid-type=char

keystore and trust store default format change

In 3.9, JKS is no longer the default keystore and trust store format. Quarkus makes an educated guess based on the file extension:

  • .pem, .crt, .key are read as PEM certificates and keys

  • .jks are read as JKS key stores and trust stores

  • .p12 and .pfx are read as PKCS12 key stores and trust stores

If your file does not use one of these extensions, you need to set the format using:

quarkus.http.ssl.certificate.key-store-file-type=JKS # or P12 or PEM
quarkus.http.ssl.certificate.trust-store-file-type=JKS # or P12 or PEM

JKS is less and less used. Since Java 9, the default keystore format in Java is PKCS12. The most significant difference between JKS and PKCS12 is that JKS is a format specific to Java. At the same time, PKCS12 is a standardized and language-neutral way of storing encrypted private keys and certificates.

Clone this wiki locally