This guide discusses migration to Hibernate ORM version 7.1. For migration from earlier versions, see any other pertinent migration guides as well.
Requirements
See the website for the list of requirements for the 7.1 series.
New Features
See the website for the list of new features in the 7.1 series.
Changes to API
This section describes changes to contracts (classes, interfaces, methods, etc.) which are considered API.
LockOptions
7.0 begins the process of reducing the visibility of org.hibernate.LockOptions
.
This class was originally exposed as an API, even though it is more properly an SPI.
From an API perspective, FindOption
, LockOption
and RefreshOption
are much better ways to specify this information.
The class itself, as well as API methods which expose it, have been deprecated.
However, 2 aspects of LockOptions
have been completely removed.
First, LockOptions
previously defined a number of constants which have been removed.
Secondly, the ability to define different LockModes for individual aliases has been removed.
ALias-specific LockModes was a very misleading feature, as Hibernate would only ever use the "greatest" LockMode. We plan to add the ability to specify a list of aliases to be locked in a later release. See https://hibernate.atlassian.net/browse/HHH-19664 for details.
Application code using org.hibernate.LockOptions
should migrate to using FindOption
,
LockOption
and RefreshOption
to control the various aspects of locking. E.g.
LockOptions lockOptions = new LockOptions();
lockOptions.setLockMode(PESSIMISTIC_WRITE);
lockOptions.setTimeout(1000);
session.refresh(book, lockOptions);
can instead be written as
session.refresh(book,
PESSIMISTIC_WRITE,
Timeout.milliseconds(1000));
Bytecode Enhancement Options
We plan to remove two options of bytecode enhancement and have currently marked them as deprecated.
First is bidirectional association management. Applications should instead manage both sides of such associations directly as we have always recommended.
Second is a little-known feature called "extended" enhancement. Applications should instead use proper object-oriented encapsulation, exposing managed state via getters and setters.
Additionally, attempting to re-enhance a class with different options is no longer allowed and will result in a FeatureMismatchException
.
Session#getLobHelper
The Session#getLobHelper
method has been marked as deprecated in favor of the static Hibernate#getLobHelper
and will be removed in a future major version.
WAIT, NO WAIT and SKIP LOCKED for H2
The for-update clause enhancements of H2 2.2.220 are now reflected in the Hibernate ORM dialect, allowing applications to use wait
, no wait
and skip locked
options.
Changes to SPI
Force-increment Locking for Version with Custom Generator
A new event type (FORCE_INCREMENT
) has been added to
org.hibernate.generator.EventType
to support
OPTIMISTIC_FORCE_INCREMENT
and PESSIMISTIC_FORCE_INCREMENT
when used with @Version
mappings with custom generators.
Pessimistic Locking
A number of changes have been made to pessimistic locking support.
-
Introduction of
org.hibernate.dialect.lock.spi.LockingSupport
which represents a Dialect’s support for pessimistic locking. -
Introduction of
org.hibernate.sql.ast.spi.LockingClauseStrategy
to integrate into SQL AST translation. -
Changed standard implementation of
org.hibernate.dialect.lock.LockingStrategy
for pessimistic locking to one using SQL AST. -
Changes to
LockOptions
as already discussed.
More changes related to pessimistic locking are coming in later 7.x releases. We’ve opted to tackle these in stages since they all relate and build on top of each other. See https://hibernate.atlassian.net/browse/HHH-19551 for details. |
JSON FormatMapper Enhancements
JSON mappings on Oracle 21+ will now try to leverage driver built-in OSON decoding to improve JSON parsing performance. In case of trouble, this can be disabled with the hibernate.dialect.oracle.oson_format_disabled
configuration option.
Enhancement Option Granularity
The actual enhancements written into bytecode were previously allowed to vary by class and sometimes even by attribute.
However, all Hibernate tooling only supported setting those "globally" per enhancement.
To this end, all org.hibernate.bytecode.enhance.spi.EnhancementContext
methods which determine whether certain aspects of enhancement are applied have changed to no longer accept class/attribute.
Specifically:
-
doDirtyCheckingInline(UnloadedClass classDescriptor)
→doDirtyCheckingInline()
-
doExtendedEnhancement(UnloadedClass classDescriptor)
→doExtendedEnhancement()
-
doBiDirectionalAssociationManagement(UnloadedField field)
→doBiDirectionalAssociationManagement()
See also Bytecode Enhancement Options.
Changes to DDL generation
This section describes changes to DDL generated by the schema export tooling. Such changes typically do not impact programs using a relational schema managed externally to Hibernate.
Automatic check constraints with single table inheritance mappings
Previously, the non-nullability of the column mapped by an attribute declared optional=false
by a subclass in a single table inheritance hierarchy was not enforced by the database.
Hibernate now automatically generates DDL check
constraints to enforce the non-nullability of such columns.