134 lines
4.7 KiB
Plaintext
134 lines
4.7 KiB
Plaintext
= 5.3 Migration Guide
|
|
:toc:
|
|
|
|
This guide discusses migration from Hibernate ORM version 5.2 to version 5.3. For migration from
|
|
earlier versions, see any other pertinent migration guides as well.
|
|
|
|
== Background
|
|
|
|
5.3 represents a JPA 2.2 compatible version on top of 5.2
|
|
|
|
|
|
== 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`.
|
|
====
|
|
|
|
=== Change in the `@TableGenerator` and `@SequenceGenerator` name scope
|
|
|
|
In order to be compliant with the JPA specification, generators names are now considered global (e.g. https://hibernate.atlassian.net/browse/HHH-12157[HHH-12157]) .
|
|
Configuring two generators, even if with different types but with the same name will now cause a `java.lang.IllegalArgumentException' to be thrown at boot time.
|
|
|
|
For example, the following mappings are no longer valid:
|
|
|
|
[source,java]
|
|
----
|
|
@Entity
|
|
@TableGenerator(name = "ID_GENERATOR", ... )
|
|
public class FirstEntity {
|
|
....
|
|
}
|
|
|
|
@Entity
|
|
@TableGenerator(name = "ID_GENERATOR", ... )
|
|
public class SecondEntity {
|
|
....
|
|
}
|
|
----
|
|
|
|
or
|
|
|
|
[source,java]
|
|
----
|
|
@Entity
|
|
@TableGenerator(name = "ID_GENERATOR", ... )
|
|
public class FirstEntity {
|
|
....
|
|
}
|
|
|
|
@Entity
|
|
@SequenceGenerator(name="ID_GENERATOR", ... )
|
|
public class SecondEntity {
|
|
....
|
|
}
|
|
----
|
|
|
|
The solution is to make all generators unique so that there are no two generators with the same name.
|
|
|
|
|
|
=== 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.
|
|
====
|
|
|
|
|
|
=== 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.
|
|
|
|
|
|
==== Second-level cache provider SPI changes
|
|
|
|
As a fix for a potentially nasty bug in caching, we needed to redesign the Second-level cache provider
|
|
SPI. Details can be seen on the https://hibernate.atlassian.net/browse/HHH-11356[HHH-11356] Jira issue.
|
|
Originally slated for 6.0 - to avoid the SPI changes, it was decided to back-port it to 5.3 because the
|
|
bug became really important.
|
|
|
|
One manifestation of this is the clarification that a single second-level cache region
|
|
may not be used to store both query-results and domain-data (entity, collection and natural-id).
|
|
|
|
Care was taken to maintain backwards compatibility so that applications could continue unchanged,
|
|
although the older access methods have been deprecated as described above.
|
|
|
|
|
|
==== Statistics changes
|
|
|
|
The change for HHH-11356 required changes in its consumers. One such consumer is the Hibernate
|
|
Statistics system....
|
|
|
|
|
|
==== Cache regionName expectations in API and SPI calls
|
|
|
|
prefixed v. un-prefixed
|
|
|
|
|
|
==== Type system changes
|
|
|
|
Use of NavigableRole, back-ported from 6.0 |