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.

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