472 lines
16 KiB
Plaintext
472 lines
16 KiB
Plaintext
= 6.0 Migration Guide
|
|
:toc:
|
|
:user-guide-base: https://docs.jboss.org/hibernate/orm/6.0/userguide/html_single/Hibernate_User_Guide.html
|
|
:javadoc-base: https://link.to/hibernate/javadoc
|
|
:java-javadoc-base: https://docs.oracle.com/en/java/javase/11/docs/api/java.base
|
|
:fn-converter:Think `AttributeConverter`
|
|
|
|
This guide discusses migration from Hibernate ORM version 6.0. For migration from
|
|
earlier versions, see any other pertinent migration guides as well.
|
|
|
|
|
|
== Known changes
|
|
|
|
=== Jakarta Persistence
|
|
|
|
6.0 moves from Java Persistence as defined by the Java EE specs to
|
|
Jakarta Persistence as defined by the Jakarta EE spec. The most immediate
|
|
impact of this change is that applications would need to be updated to use
|
|
the Jakarata Persistence classes (`jakarta.persistence.*`) instead of the Java
|
|
Persistence ones (`javax.persistence.*`).
|
|
|
|
The Jakarta spec also renames the JPA settings (again, from `javax.persistence.*` to
|
|
'jakarta.persistence.*') and defines a new set of XSD namespaces for `orm.xml` and
|
|
`persistence.xml` files.
|
|
|
|
Jakarta provides a https://github.com/eclipse/transformer[transformer]
|
|
tool which, along with appropriate "rules", will transform a project from Java Persistence to
|
|
Jakarta Persistence. This can update package names in source, settings, xsd references and more.
|
|
|
|
NOTE: As far as the XSD and setting changes, Hibernate does support both sets as a temporary aid
|
|
in migration. It logs a deprecation warning when the Java EE variants are used. See the `rules/`
|
|
directory in the project root for the configuration used to migrate Hibernate itself.
|
|
|
|
|
|
=== Java 11
|
|
|
|
With 6.0, Hibernate ORM has moved to expect Java 11 as its baseline version
|
|
|
|
|
|
[[read-jdbc]]
|
|
=== Reading from JDBC
|
|
|
|
Throughput testing of Hibernate was showing that its use of reading JDBC values by name, rather than
|
|
by position was its limiting factor in any further scaling in terms of throughput.
|
|
|
|
This is the main reason for most of the changes in Hibernate 6.
|
|
|
|
This seemingly simple change, however, ripples through quite a few contracts - including some
|
|
APIs and some SPIs
|
|
|
|
|
|
==== Replace read-by-name with read-by-position
|
|
|
|
Various contracts in `org.hibernate.type` and `org.hibernate.usertype` were changed to now offer a read-by-position
|
|
method. The read-by-name methods were removed.
|
|
Read-by-position rather than read-by-name
|
|
|
|
|
|
[[type]]
|
|
=== Type system / custom types
|
|
|
|
Another change is to generally modernize Hibernate's mapping annotations and make them
|
|
more type-safe.
|
|
|
|
We decided this is the right time since 6.0 is a major release and most of the type-related
|
|
contracts were already changing to implement the <<read-jdbc,read-by-position>> changes.
|
|
|
|
One part of this work was the removal of various String-based approaches for specifying Types to use from annotations, including
|
|
the removal of `@Type`, `@AnyMetaDef`, `@AnyMetaDefs`, `@MapKeyType`, @TypeDef` and `@TypeDefs`, as well as
|
|
removing annotation attributes accepting the type to use as a String (e.g. `org.hibernate.annotations.CollectionType#type`)
|
|
|
|
The Hibernate {user-guide-base}?type[User Guide] covers the details of mapping your domain model.
|
|
// todo (6.0) - find proper id syntax for "domain model" type ^^
|
|
|
|
|
|
[[rename-java-type]]
|
|
==== Renaming of JavaTypeDescriptor contract
|
|
|
|
The interface `org.hibernate.type.descriptor.java.JavaTypeDescriptor` has been renamed to
|
|
`org.hibernate.type.descriptor.java.JavaType`
|
|
|
|
|
|
[[rename-jdbc-type]]
|
|
==== Renaming of SqlTypeDescriptor contract
|
|
|
|
The interface `org.hibernate.type.descriptor.sql.SqlTypeDescriptor` has been renamed to
|
|
`org.hibernate.type.descriptor.jdbc.JdbcType`
|
|
|
|
|
|
[[basic-type]]
|
|
==== Basic types
|
|
|
|
Basic types are no longer exposed as customizable. Instead, users configure
|
|
the different aspects of mapping the basic value to the database -
|
|
|
|
* `JavaType`
|
|
* `JdbcType`
|
|
* `BasicValueConverter`{fn-converter}
|
|
* `MutabilityPlan`
|
|
|
|
See the Hibernate {user-guide-base}?basic-type[User Guide] for details of mapping
|
|
// todo (6.0) - find proper id syntax for "domain model" basic-type ^^
|
|
basic values in your domain model, including how to influence these 4 aspects.
|
|
|
|
This also made the various implementations of `BasicType` obsolete, thus they have been removed.
|
|
`NamedBasicTypeImpl` takes the role of all the previous specific implementations by wrapping a
|
|
`JdbcType` and `JavaType`.
|
|
|
|
The `StandardBasicTypes` class previously exposed `BasicType` instance fields, which now have been replaced with fields
|
|
of the type `BasicTypeReference`. APIs that previously accepted just a `BasicType` have been adapted to also accept a
|
|
`BasicTypeReference` which allows for uses of `StandardBasicType` fields to stay mostly source compatible.
|
|
|
|
|
|
==== Embeddables / components
|
|
|
|
Addition of `EmbeddableInstantiator`
|
|
|
|
Constructor injection. Embeddables used as identifiers cannot use constructor injection.
|
|
See the Hibernate {user-guide-base}?embeddable-type[User Guide] for details.
|
|
// todo (6.0) - find proper id syntax for "domain model" embeddable-type ^^
|
|
|
|
Multiple component mappings for the same java class with different property mappings is no
|
|
longer supported. Every property mapping combination should have its own java class
|
|
|
|
|
|
==== Plural attributes
|
|
|
|
`@CollectionClassification`
|
|
`@CollectionSemantics`
|
|
`@CollectionType`
|
|
|
|
|
|
|
|
|
|
|
|
[[query]]
|
|
=== Query
|
|
|
|
|
|
[[query-sqm]]
|
|
==== SQM
|
|
|
|
todo (6.0) - cover functions
|
|
todo (6.0) - cover new temporal capabilities
|
|
todo (6.0) - cover new syntaxes
|
|
todo (6.0) - cover bulk manipulation query handling
|
|
|
|
|
|
[[query-sqm-rows]]
|
|
==== Result "rows"
|
|
|
|
Queries that use joins without specifying a select clause (e.g. `from Person p join p.address`)
|
|
used to return a `List<Object[]>`. Starting with 6.0, such a query instead returns
|
|
`List<Person>`
|
|
|
|
The HQL query `select p, a from Person p join p.address a` returns instead a `List<Object[]>`.
|
|
|
|
```
|
|
List<Person> result = session.createQuery("from Person p join p.address").list();
|
|
List<Object[]> results = session.createQuery("select p, a from Person p join p.address a").list();
|
|
```
|
|
|
|
|
|
[[query-sqm-pass-thru]]
|
|
===== Pass-through tokens
|
|
|
|
The use of plain HQL identifiers in e.g. functions which couldn't be interpreted as an attribute of a `FROM` root
|
|
were passed through as-is to SQL in Hibernate 5.x which was dropped in 6.0 because we believe this is unsafe
|
|
and might lead to surprising results. HQL queries that relied on this, need to be changed and use the newly introduced
|
|
`sql` function, which allows passing through the content of a string literal to SQL.
|
|
|
|
An HQL query like `select substring( e.description, 21, 11, octets ) from AnEntity e`, which relies on this for passing through `octets`
|
|
can be migrated to `select substring( e.description, 21, 11, sql('octets') ) from AnEntity e`.
|
|
|
|
|
|
[[query-sqm-distinct]]
|
|
===== DISTINCT
|
|
|
|
Starting with Hibernate ORM 6 it is no longer necessary to use *distinct* in JPQL and HQL
|
|
to filter out the same parent entity references when join fetching a child collection.
|
|
The returning duplicates of entities are now always filtered by Hibernate.
|
|
|
|
Which means that for instance it is no longer necessary to set `QueryHints#HINT_PASS_DISTINCT_THROUGH` to `false`
|
|
in order to skip the entity duplicates without producing a `distinct` in the SQL query.
|
|
|
|
From Hibernate ORM 6, `distinct` is always passed to the SQL query and the flag `QueryHints#HINT_PASS_DISTINCT_THROUGH`
|
|
has been removed.
|
|
|
|
|
|
===== Association Comparisons
|
|
|
|
Previously Hibernate did allow comparing an association with an FK value like `... where alias.association = 1`
|
|
or `... where alias.association = alias.association.id` or even `... where alias.association = :param` where `param`
|
|
is bound to an integer `1`. This was supported prior to Hibernate 6.0 if the foreign key for the association is an integer.
|
|
|
|
The right way to do this is de-referencing the association by the FK attribute `... where alias.association.id = 1`
|
|
which is guaranteed to not produce a join, or use an entity reference for `... where alias.association = :param`
|
|
where `param` is bound to `entityManager.getReference(EntityClass.class, 1)`.
|
|
|
|
|
|
|
|
[[query-sqm-psuedo-attr]]
|
|
===== Collection psuedo-attributes
|
|
|
|
Prior to 6.0, it was possible to de-reference special properties on plural attributes like `size` which was dropped.
|
|
The special properties lead to confusion and were sometimes ambiguous. The replacement is the function syntax.
|
|
|
|
size::
|
|
The collection size can be determined by using the `size( pluralAttribute )` function instead
|
|
|
|
elements::
|
|
The collection elements can be referred to by using the `value( pluralAttribute )` function instead
|
|
|
|
indices::
|
|
The collection indices can be referred to by using the `index( pluralAttribute )` or `key( pluralAttribute )` function instead
|
|
|
|
index::
|
|
The collection index can be referred to by using the `index( pluralAttribute )` or `key( pluralAttribute )` function instead
|
|
|
|
maxindex::
|
|
The collection maximum index can be determined by using the `maxindex( pluralAttribute )` function instead
|
|
|
|
minindex::
|
|
The collection minimum index can be determined by using the `minindex( pluralAttribute )` function instead
|
|
|
|
maxelement::
|
|
The collection maximum element can be determined by using the `maxelement( pluralAttribute )` function instead
|
|
|
|
minelement::
|
|
The collection minimum element can be determined by using the `minelement( pluralAttribute )` function instead
|
|
|
|
|
|
|
|
[[query-native]]
|
|
==== Native
|
|
|
|
Using NativeQuery to call a SQL function is no longer supported.
|
|
|
|
Given the `NamedNativeQuery`
|
|
```
|
|
@NamedNativeQuery(
|
|
name = "fn_person_and_phones",
|
|
query = "{ ? = call fn_person_and_phones( ? ) }",
|
|
callable = true,
|
|
resultSetMapping = "person_with_phones"
|
|
)
|
|
```
|
|
|
|
the code
|
|
```
|
|
scope.inTransaction(
|
|
entityManager -> {
|
|
try {
|
|
List<Object[]> postAndComments = entityManager.createNamedQuery("fn_person_and_phones" ).setParameter( 1, 1L ).getResultList();
|
|
```
|
|
|
|
is going to throw an `IllegalArgumentException`.
|
|
|
|
If you want to retain the named version, you can change the definition to
|
|
|
|
```
|
|
@NamedStoredProcedureQuery(
|
|
name = "fn_person_and_phones",
|
|
procedureName = "fn_person_and_phones",
|
|
resultSetMapping = "person_with_phones",
|
|
hints = @QueryHint(name = "org.hibernate.callableFunction", value = "true"),
|
|
parameters = {
|
|
@StoredProcedureParameter(type = Long.class)
|
|
}
|
|
)
|
|
```
|
|
|
|
and call this like
|
|
```
|
|
List<Object[]> postAndComments = entityManager.createNamedStoredProcedureQuery( "fn_person_and_phones" ).setParameter( 1, 1L ).getResultList();
|
|
```
|
|
|
|
or not define the stored procedure and use this code
|
|
```
|
|
List<Object[]> postAndComments = entityManager.createStoredProcedureQuery( "fn_person_and_phones", "person_with_phones" ).setParameter( 1, 1L ).getResultList();
|
|
```
|
|
|
|
[[query-stream]]
|
|
==== Stream
|
|
|
|
`jakarta.persistence.Query#getResultStream()` and `org.hibernate.query.Query#stream()` no longer
|
|
return a `Stream` decorator. In order to close the underlying IO resources, it is now necessary to
|
|
explicitly call the `Stream#close()` method.
|
|
|
|
This change makes the Streams returned by Hibernate behave as defined in the JDK
|
|
link:{java-javadoc-base}/java/util/stream/Stream.html[Stream] documentation, which is quite
|
|
explicit about the need for an explicit call to `close` by the user to avoid resource leakages.
|
|
|
|
|
|
[[query-iterate]]
|
|
==== Iterate
|
|
|
|
The `Query#iterate()` method has been removed. The alternative is to use `Query#stream()` or `Query#getResultStream()`.
|
|
|
|
|
|
[[query-ordinal-param]]
|
|
==== Ordinal Parameters binding
|
|
|
|
HQL ordinal parameter binding is 1-based, this means that queries like
|
|
|
|
```
|
|
s.createQuery( "select p from Parent p where id in ?0", Parent.class );
|
|
query.setParameter( 0, Arrays.asList( 0, 1, 2, 3 ) );
|
|
```
|
|
|
|
that uses a 0-based positional binding are not supported, and they should be changed to the following
|
|
|
|
```
|
|
s.createQuery( "select p from Parent p where id in ?`", Parent.class );
|
|
query.setParameter( 1, Arrays.asList( 0, 1, 2, 3 ) );
|
|
```
|
|
|
|
|
|
[[proc-call]]
|
|
=== ProcedureCall
|
|
|
|
|
|
[[proc-call-param]]
|
|
==== Procedure Parameters
|
|
|
|
For parameters defined on a ProcedureCall as accepting binding (IN and INOUT), a distinction is now
|
|
made between whether `setParameter` is called or not. If `setParameter` was called, whatever value
|
|
was set by the user is passed to the database. If it was not called, Hibernate will not
|
|
set any value which triggers the default value defined on the database procedure argument be used
|
|
|
|
|
|
|
|
=== Removals
|
|
|
|
* JMX integration
|
|
* JACC integration
|
|
* @Deprecated features:
|
|
** 'hibernate.classLoader.application', 'hibernate.classLoader.resources', 'hibernate.classLoader.hibernate' and 'hibernate.classLoader.environment': use 'hibernate.classLoaders' instead.
|
|
** 'hibernate.hbm2dll.create_namespaces': use 'jakarta.persistence.create-database-schemas' or 'hibernate.hbm2ddl.create_namespaces'
|
|
|
|
=== org.hibernate.Interceptors
|
|
|
|
The method
|
|
```
|
|
boolean onSave(Object entity, Serializable id, Object[] state, String[] propertyNames, Type[] types)
|
|
```
|
|
|
|
has been removed in favour of
|
|
```
|
|
boolean onSave(Object entity, Object id, Object[] state, String[] propertyNames, Type[] types)
|
|
```
|
|
|
|
|
|
|
|
=== Fetch behaviour change
|
|
|
|
We changed the way we detect circularity, we do not follow anymore a deep first detection, so what happens is that in a model like
|
|
|
|
```
|
|
@Entity
|
|
class Node {
|
|
|
|
@ManyToOne
|
|
Node node1;
|
|
|
|
@ManyToOne
|
|
Node node2;
|
|
|
|
}
|
|
```
|
|
|
|
being all eager we are executing a query with 4 joins
|
|
|
|
```
|
|
FROM Node
|
|
JOIN Node.node1
|
|
JOIN Node.node1.node2
|
|
JOIN Node.node2
|
|
JOIN Node.node2.node1
|
|
```
|
|
|
|
whereas before we
|
|
```
|
|
FROM Node
|
|
JOIN Node.node1
|
|
JOIN Node.node1.node2
|
|
```
|
|
|
|
and issue a select for `Node.node2` if the FK of `Node.node2` is not null
|
|
|
|
```
|
|
FROM Node.node2
|
|
JOIN Node.node2.node1
|
|
JOIN Node.node2.node1.node2
|
|
```
|
|
|
|
In this simple example this is not such a big deal, but if we increase the number of eager fetched self-associations
|
|
to e.g. 3 like here:
|
|
|
|
```
|
|
@Entity
|
|
class Node {
|
|
|
|
@ManyToOne
|
|
Node node1;
|
|
|
|
@ManyToOne
|
|
Node node2;
|
|
|
|
@ManyToOne
|
|
Node node3;
|
|
|
|
}
|
|
```
|
|
|
|
this results in mind-blowing 15 joins
|
|
|
|
```
|
|
FROM Node
|
|
JOIN Node.node1
|
|
JOIN Node.node1.node2
|
|
JOIN Node.node1.node2.node3
|
|
JOIN Node.node1.node3
|
|
JOIN Node.node1.node3.node2
|
|
JOIN Node.node2
|
|
JOIN Node.node2.node1
|
|
JOIN Node.node2.node1.node3
|
|
JOIN Node.node2.node3
|
|
JOIN Node.node2.node3.node1
|
|
JOIN Node.node3
|
|
JOIN Node.node3.node1
|
|
JOIN Node.node3.node1.node2
|
|
JOIN Node.node3.node2
|
|
JOIN Node.node3.node2.node1
|
|
```
|
|
|
|
as you can see, this leads to a lot of joins very quickly, but the behavior of 5.x simply was not intuitive.
|
|
To avoid creating so many joins, and also in general, we recommend that you use lazy fetching i.e. `@ManyToOne(fetch = FetchType.LAZY)`
|
|
or `@OneToOne(fetch = FetchType.LAZY)` for most associations, but this is especially important if you have multiple self-referencing associations as you can see in the example.
|
|
|
|
|
|
=== Removal of legacy Hibernate Criteria API
|
|
|
|
The legacy Hibernate Criteria API which was deprecated back in Hibernate 5.x was removed in 6.0.
|
|
Usually, all queries using the legacy API can be modeled with the JPA Criteria API.
|
|
In some cases it is necessary to use the Hibernate JPA Criteria extensions.
|
|
|
|
|
|
=== Restructuring of `org.hibernate.loader`
|
|
|
|
The contents of the `loader.collection` package were restructured into `loader.ast.spi` and `loader.ast.internal`
|
|
as well as adapted to the SQM API.
|
|
|
|
The contents of `loader.custom` were adapted and moved to `query.sql`.
|
|
|
|
The contents of `loader.entity` and `loader.plan` were removed
|
|
|
|
|
|
=== Restructuring of the sql package
|
|
|
|
The contents of `sql.ordering` were adapted and moved to `metamodel.mapping.ordering.ast`.
|
|
|
|
Classes of the `sql` package that were previously used for building SQL, but aren't needed anymore, were removed.
|
|
The SQL generation is now fully handled through the `SqlAstTranslator` which a `Dialect` exposes a factory for.
|
|
|
|
|
|
|
|
|
|
==== Misc
|
|
|
|
* The default type for `Duration` was changed to `NUMERIC` which could lead to schema validation errors
|