138 lines
4.5 KiB
Plaintext
138 lines
4.5 KiB
Plaintext
= 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 |