hibernate-orm/migration-guide.adoc

85 lines
3.3 KiB
Plaintext

= 7.0 Migration Guide
:toc:
:toclevels: 4
:docsBase: https://docs.jboss.org/hibernate/orm
:versionDocBase: {docsBase}/6.4
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
:javadocsBase: {versionDocBase}/javadocs
This guide discusses migration to Hibernate ORM version 7.0. For migration from
earlier versions, see any other pertinent migration guides as well.
[[jpa-32]]
== JPA 3.2
7.0 migrates to JPA 3.2 which is fairly disruptive, mainly around:
* type parameters
** Affects much of the Criteria API - especially roots, joins, paths
** Affects much of the Graph API -
*** org.hibernate.graph.Graph.addAttributeNode(java.lang.String) defines a return while
1jakarta.persistence.Graph.addAttributeNode(java.lang.String)` does not.
* new JPA features colliding with previous Hibernate extension features
** `Nulls` (JPA) v. `NullPrecedence` (Hibernate), including JPA's new `Order#getNullPrecedence()` returning `Nulls`
colliding with Hibernate's `SqmSortSpecification#getNullPrecedence` returning `NullPrecedence`. Hibernate's form
was renamed to `SqmSortSpecification#getHibernateNullPrecedence` to avoid the collision.
** `SchemaManager` is now also a JPA contract exposed as `EntityManagerFactory#getSchemaManager` which leads to type issues for
Hibernate's `SessionFactory#getSchemaManager`. Hibernate's `SchemaManager` now extends the new JPA `SchemaManager`.
But that is a bytecode incompatibility.
** JPA has added support in its Graph API for things Hibernate has supported for some time. Some of those are collisions
requiring changes to the Hibernate API.
[[annotation-validation]]
== Annotation Validations
7.0 adds many more checks about illegal use of annotations.
=== Access
The Jakarta Persistence specification says that it is illegal to specify `@Access(FIELD)` on a property (getter)
or to use `@Access(PROPERTY)` on a field. As of 7.0, Hibernate now throws an exception when this condition is
discovered.
=== PersistentAttributeType
As of 7.0, Hibernate applies much better validation of an attribute specifying multiple PersistentAttributeTypes.
Jakarta Persistence 3.2 has clarified this in the specification. E.g., the following examples are all now illegal -
[source,java]
----
@Basic
@ManyToOne
private Employee manager;
----
or
[source,java]
----
@Lob
@ManyToOne
private Employee manager;
----
[[cleanup]]
== Some Cleanup
* Removed `SqmQualifiedJoin`. All joins are qualified.
[[todo]]
== Todos
NOTE:: Look for `// todo (jpa 3.2)`
* Deprecate `SqmQualifiedJoin` in 6.x
* {@linkplain SqmCrossJoin} and its offspring are largely de-typed to account
for {@linkplain SqmCrossJoin} having only one type argument for the right-hand
side. To properly handle the type parameters in the hierarchy we need to change this to
accept type parameter for the left-handle side as well - breaking change.
* The changes in `jakarta.persistence.EntityManager#createNativeQuery(java.lang.String, java.lang.Class<?>)` are really unfortunate.
Previously that signature was `(java.lang.String, java.lang.Class)` and our override of that was able to be
`<R> NativeQuery<R> createNativeQuery(String sqlString, Class<R> resultClass)`. JPA adding that wildcard means our
override is no longer valid. I had to change that to ``