Skip to content

Latest commit

 

History

History
94 lines (71 loc) · 4.18 KB

migration-guide.adoc

File metadata and controls

94 lines (71 loc) · 4.18 KB
Raw

6.3 Migration Guide

Table of Contents

This guide discusses migration to Hibernate ORM version 6.3. For migration from earlier versions, see any other pertinent migration guides as well.

HQL Numeric Literal Types

Version 3.2 of the Jakarta Persistence specification clarifies the interpretation of numeric literals with regard to type, explicitly aligning with the Java specification (as well as adopting Hibernate’s long-standing BigInteger and BigDecimal suffixes). HQL and JPQL are domain/object-level queries, so that makes perfect sense.

  • Integer - 123

  • Long - 123l, 123L

  • BigInteger - 123bi, 123BI

  • Double - 123.4

  • Float - 123.4f, 123.4F

  • BigDecimal - 123.4bd, 123.4BD

Hibernate 6.3 aligns with those interpretations, which may lead to different behavior from prior versions.

Batch Fetching and LockMode

When LockMode is greater than READ Hibernate does not execute the batch fetching so existing uninitialized proxies will not be initialized. This because the lock mode is different from the one of the proxies in the batch fetch queue.

E.g.

MyEntity proxy = session.getReference( MyEntity.class, 1 );
MyEntity myEntity = session.find(MyEntity.class, 2, LockMode.WRITE);

only the entity with id equals to 2 will be loaded but the proxy will not be initialized.

Integrating Static Metamodel Generation

The integration of static metamodel generation in a project has changed; the recommended way to do this now is by harnessing the annotation processor classpath. This is true for both Gradle and Maven.

Some projects currently integrate with hibernate-jpamodelgen with a dependency, like so:

    <dependencies>
        <!-- ... -->
        <!-- THIS IS WRONG! See below -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-jpamodelgen</artifactId>
            <scope>provided</scope>
            <version>6.3.1</version> <!-- Optional, may be managed by a BOM -->
        </dependency>
        <!-- ... -->
    </dependencies>

If you are in that case, in previous versions of Hibernate ORM you were leaking dependencies of hibernate-jpamodelgen into your compile classpath unknowingly. With Hibernate ORM 6.3, you may now experience a compilation error during annotation processing related to missing Antlr classes. To get rid of that error:

  1. Check out the specific sections in the User Guide for a guideline on how to properly harness the annotation processor classpath to use hibernate-jpamodelgen: see here for Gradle or here for Maven.

  2. If you use Maven and the annotation processor classpath doesn’t seem to properly get the version of hibernate-jpamodelgen from dependency management or your BOM, make sure you’re using Maven Compiler Plugin 3.12.0 or later: older versions didn’t handle dependency management for annotationProcessorPath entries.

HQL null literal comparison

In prior versions of Hibernate it was possible to compare expressions against a null literal with the = and <>/!= operators. This is counter-intuitive as the comparison against a parameter or expression that resolves to a null would always yield false i.e. no results.

As of Hibernate ORM 6.3, this special treatment in HQL was removed without a way to retain backwards compatibility. Users should migrate queries to use the is null and is not null predicate syntax instead.