HHH-12820 Initialize the 5.4 migration guide
This commit is contained in:
Guillaume Smet
parent
2733a3cb09
commit
2fd89dcc1a
|
|
@ -1,134 +1,11 @@
|
|||
= 5.3 Migration Guide
|
||||
= 5.4 Migration Guide
|
||||
:toc:
|
||||
|
||||
This guide discusses migration from Hibernate ORM version 5.2 to version 5.3. For migration from
|
||||
This guide discusses migration from Hibernate ORM version 5.3 to version 5.4. For migration from
|
||||
earlier versions, see any other pertinent migration guides as well.
|
||||
|
||||
== Background
|
||||
|
||||
Hibernate 5.3 adds support for the JPA 2.2 specification
|
||||
|
||||
|
||||
== Known changes
|
||||
|
||||
=== Changes to positional query parameter handling
|
||||
|
||||
This really breaks down into 2 related changes:
|
||||
|
||||
* Support for JDBC-style parameter declarations in HQL/JPQL queries has been removed. This feature
|
||||
has been deprecated since 4.1 and removing it made implementing the second change, so we decided
|
||||
to remove that support. JDBC-style parameter declaration is still supported in native-queries.
|
||||
* Since JPA positional parameters really behave more like named parameters (they can be repeated,
|
||||
declared in any order, etc.) Hibernate used to treat them as named parameters - it relied on
|
||||
Hibernate's JPA wrapper to interpret the JPA setParameter calls and properly handle delegating to
|
||||
the named variant. This is actually a regression in 5.2 as it causes
|
||||
`javax.persistence.Parameter#getPosition` to report `null`.
|
||||
|
||||
For JDBC-style parameter declarations in native queries, we have also moved to using one-based
|
||||
instead of zero-based parameter binding to be consistent with JPA. That can temporarily be
|
||||
reverted by setting the `hibernate.query.sql.jdbc_style_params_base` setting to `true` which
|
||||
reverts to expecting zero-based binding.
|
||||
|
||||
|
||||
=== Change in the `@TableGenerator` stored value
|
||||
|
||||
In order to be compliant with the JPA specification, the sequence value stored by Hibernate 5.3 in the database table used by the `javax.persistence.TableGenerator`
|
||||
is the *last* generated value. Previously, Hibernate stored the *next* sequence value.
|
||||
|
||||
For backward compatibility, a new setting called `hibernate.id.generator.stored_last_used` was introduced, which gives you the opportunity to fall back to the old Hibernate behavior.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Existing applications migrating to 5.3 and using the `@TableGenerator` have to set the `hibernate.id.generator.stored_last_used` configuration property to `false`.
|
||||
====
|
||||
|
||||
|
||||
=== Second-level cache provider SPI changes
|
||||
|
||||
Hibernate's second-level cache SPI needed to be redesigned to match with expectations between
|
||||
Hibernate and the various caching providers. And the SPI did not really clarify the intention.
|
||||
These mis-matched expectations certainly had the potential to lead to bugs. Although it was
|
||||
originally slated for 6.0 to delay the SPI changes, we decided to back-port the work to
|
||||
5.3 to address a number of bugs that could have been avoided with a clarified SPI.
|
||||
|
||||
The changes also allow the caching providers to perform serious optimizations based on
|
||||
the users configuration of domain data caching in Hibernate.
|
||||
|
||||
Details can be seen on the https://hibernate.atlassian.net/browse/HHH-11356[HHH-11356] Jira issue
|
||||
|
||||
One potential upgrade concern is any custom `org.hibernate.cache.spi.QueryCacheFactory` implementations.
|
||||
`org.hibernate.cache.spi.QueryCacheFactory` was meant as a means to allow service providers the
|
||||
ability to define query result caching, generally with more stale-tolerant query result invalidation handling.
|
||||
However, the contract also bound it to the old second level cache contracts so they had to be
|
||||
updated. Its responsibilities also changed so we also decided to "rename it" to
|
||||
`org.hibernate.cache.spi.TimestampsCacheFactory`
|
||||
|
||||
Another specific change to be aware of is accessing cache entries via `SecondLevelCacheStatistics#getEntries`
|
||||
and `NaturalIdCacheStatistics#getEntries`. These methods have been deprecated, however the new
|
||||
caching SPI does not really require caching providers to support this. As of 5.3 these methods
|
||||
inherently return an empty Map (`Collections#emptyMap`). This has always been something that providers
|
||||
did not implement "correctly" anyway
|
||||
|
||||
|
||||
=== Statistics changes
|
||||
|
||||
The change for HHH-11356 required changes in its consumers. One such consumer is the Hibernate
|
||||
Statistics system....
|
||||
|
||||
|
||||
=== Drop hibernate-infinispan module
|
||||
|
||||
Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project so
|
||||
the `hibernate-infinispan` module has been dropped.
|
||||
|
||||
A relocation pom which is pointing to `org.infinispan:infinispan-hibernate-cache` dependency is still generated,
|
||||
therefore, avoiding the need of updating any library dependency.
|
||||
|
||||
[WARN]
|
||||
====
|
||||
The relocation pom may be dropped in a future release.
|
||||
====
|
||||
|
||||
|
||||
=== EnhancementTask changes
|
||||
|
||||
The API of the `org.hibernate.tool.enhance.EnhancementTask` Ant task was changed, specifically
|
||||
the `#addFileset` method was dropped in favor of `#setBase` and `#setDir`
|
||||
|
||||
See details on the https://hibernate.atlassian.net/browse/HHH-11795[HHH-11795] Jira issue.
|
||||
|
||||
The main gist is that EnhancementTask was fixed (through a contribution) to actually work with
|
||||
`Enhancer` from `BytecodeProvider`. Previously it had not. And part of fixing that required this
|
||||
change.
|
||||
|
||||
|
||||
=== Many-to-one association in embeddable collection elements and composite IDs
|
||||
|
||||
A bug introduced in 4.3 caused many-to-one associations in embeddable collection elements and
|
||||
composite IDs to be eagerly fetched, even when explicitly mapped as lazy.
|
||||
|
||||
This bug does not affect many-to-one associations that are not in a composite ID or embeddable
|
||||
collection element.
|
||||
|
||||
In 5.3.2, this bug was fixed. As a result, such associations will be fetched as specified
|
||||
by their mappings.
|
||||
|
||||
Many-to-one associations mapped by using native HBM xml are lazy by default. In order to keep
|
||||
the associations eager in 5.3.2 and later, mappings will need to explicitly specify that
|
||||
they are non-lazy.
|
||||
|
||||
When mapped with annotations, many-to-one associations use `FetchType.EAGER` by default.
|
||||
Starting in 5.3.2, if an association is mapped with `FetchType.LAZY`, the assocation will
|
||||
be lazily fetched, as expected.
|
||||
|
||||
See details on the https://hibernate.atlassian.net/browse/HHH-12687[HHH-12687] Jira issue.
|
||||
|
||||
=== 5.3 -> 6.0 compatibility changes
|
||||
|
||||
The original driving force behind these series of changes is an effort to be as proactive as possible
|
||||
about designing compatibility between 5.3 and 6.0.
|
||||
|
||||
|
||||
==== Type system changes
|
||||
|
||||
Use of NavigableRole, back-ported from 6.0 rather than plain String
|
||||
Loading…
Reference in New Issue