95 lines
4.2 KiB
Plaintext
95 lines
4.2 KiB
Plaintext
= 6.3 Migration Guide
|
|
:toc:
|
|
:toclevels: 4
|
|
:docsBase: https://docs.jboss.org/hibernate/orm
|
|
:versionDocBase: {docsBase}/6.3
|
|
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
|
|
:userGuideBase_6_4: {docsBase}/6.4/userguide/html_single/Hibernate_User_Guide.html
|
|
:javadocsBase: {versionDocBase}/javadocs
|
|
|
|
|
|
This guide discusses migration to Hibernate ORM version 6.3. For migration from
|
|
earlier versions, see any other pertinent migration guides as well.
|
|
|
|
* link:{docsBase}/6.2/migration-guide/migration-guide.html[6.2 Migration guide]
|
|
* link:{docsBase}/6.1/migration-guide/migration-guide.html[6.1 Migration guide]
|
|
* link:{docsBase}/6.0/migration-guide/migration-guide.html[6.0 Migration guide]
|
|
|
|
[[hql-numeric-literal-types]]
|
|
== HQL Numeric Literal Types
|
|
|
|
Version 3.2 of the Jakarta Persistence specification
|
|
https://github.com/jakartaee/persistence/issues/423[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-changes]]
|
|
== 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.
|
|
|
|
```java
|
|
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.
|
|
|
|
[[metamodel-generation]]
|
|
== 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:
|
|
|
|
[source,xml]
|
|
----
|
|
<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 {userGuideBase}#tooling-gradle-modelgen[here for Gradle] or {userGuideBase_6_4}#tooling-maven-modelgen[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:
|
|
https://issues.apache.org/jira/browse/MCOMPILER-391[older versions didn't handle dependency management for `annotationProcessorPath` entries].
|
|
|
|
[[hql-null-literal-comparison]]
|
|
== 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.
|
|
|