Skip to content

Latest commit

 

History

History
96 lines (70 loc) · 3.56 KB

migration-guide.adoc

File metadata and controls

96 lines (70 loc) · 3.56 KB
Raw

7.0 Migration Guide

Table of Contents

This guide discusses migration to Hibernate ORM version 7.0. For migration from earlier versions, see any other pertinent migration guides as well.

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.

    • Transaction#getTimeout. JPA 3.2 adds #getTimeout but uses Integer whereas Hibernate has historically used int

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 -

@Basic
@ManyToOne
private Employee manager;

or

@Lob
@ManyToOne
private Employee manager;

JavaBean Conventions

Previous versions allowed some, at beast, questionable attribute naming patterns. These are no longer supported. E.g.

@Basic
String isDefault();

Some Cleanup

  • Removed SqmQualifiedJoin. All joins are qualified.

  • Removed AdditionalJaxbMappingProducer, deprecated in favor of AdditionalMappingContributor

  • Removed MetadataContributor, deprecated in favor of AdditionalMappingContributor

Todos

NOTE

Look for // todo (jpa 3.2)

  • {@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 ``