hibernate-orm/migration-guide.adoc

= 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.


[[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 ``