hibernate-orm/migration-guide.adoc

= 7.0 Migration Guide
:toc:
:toclevels: 4
:docsBase: https://docs.jboss.org/hibernate/orm
:versionDocBase: {docsBase}/7.0
: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]]
== Jakarta Persistence 3.2

7.0 migrates to Jakarta Persistence 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
                `jakarta.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.
  ** `Transaction#getTimeout`.  JPA 3.2 adds `#getTimeout` but uses `Integer` whereas Hibernate has historically used `int`

See this https://in.relation.to/2024/04/01/jakarta-persistence-3/[blog post] for a good discussion of the changes in Jakarta Persistence 3.2.


[[hibernate-models]]
== Hibernate Models

For many years Hibernate has used the Hibernate Commons Annotations (HCANN) library for handling various low-level tasks
related to understanding the structure of an application domain model, reading annotations and weaving in XML
mapping documents.

However, HCANN suffers from a number of limitations that continue to be problematic.  And given
the use of HCANN across multiple projects, doing the needed refactoring was simply not possible.

The https://github.com/hibernate/hibernate-models[Hibernate Models] project was developed to be a better alternative
to HCANN.  Hibernate Models is essentially an abstraction over reflection (`Type`, `Class`, `Member`, ...) and
annotations.  Check out its project page for complete details.

7.0 uses Hibernate Models in place of HCANN.

NOTE: Currently, the `hibernate-envers` module still uses HCANN.  That will change during continued 7.0 development.



[[annotation-validation]]
== Annotation Validations

7.0 adds many more checks about illegal use of annotations.


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


[[misplaced-annotations]]
=== Misplaced Annotations

7.0 does much more in-depth checking that annotations appear in the proper place.  While previous versions
did not necessarily throw errors, in most cases these annotations were simply ignored.  E.g.


[source,java]
----
@Entity
class Book {
	// defines FIELD access-type
    @Id
    Integer id;

	// previously ignored, this is an error now
    @Column(name="category")
    String getType() { ... }

    ...
}
----




[[java-beans]]
== JavaBean Conventions

Previous versions allowed some questionable (at best) attribute naming patterns.  These are no longer supported.  E.g.

[source,java]
----
@Basic
String isDefault();
----



[[cleanup]]
== Some Cleanup

* Removed `SqmQualifiedJoin`.  All joins are qualified.
* Removed `AdditionalJaxbMappingProducer`, deprecated in favor of `AdditionalMappingContributor`
* Removed `MetadataContributor`, deprecated in favor of `AdditionalMappingContributor`
* Removed `@Persister`.
* Removed `hibernate.mapping.precedence` and friends


[[todo]]
== Todos (dev)

* Look for `todo (jpa 3.2)` comments
* Look for `todo (7.0)` comments