Skip to content

Commit 9b3ea72

Browse files
sebersolesebersole
committed
migration guide structure
1 parent a62aa8f commit 9b3ea72

File tree

1 file changed

+133
-94
lines changed

1 file changed

+133
-94
lines changed

‎migration-guide.adoc‎

Lines changed: 133 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,104 @@ However, the preferred approach is to explicitly batch operations via `insertMul
219219
[[api-changes]]
220220
== Changes to API
221221

222-
7.0 contains no changes to API, aside from some <<removals, removals>>.
222+
A general theme in 7.0 has been to remove Hibernate-specific features that have a direct replacement in JPA.
223+
224+
[[session-load]]
225+
=== Session#load
226+
227+
`Session#load` methods have been removed in favor of `Session#getReference` which has the same semantic.
228+
229+
[[session-refresh]]
230+
=== Session#refresh
231+
232+
The forms of `Session#refresh` accepting an entity-name have been removed; the passed entity already indicates the entity-name (even with dynamic models).
233+
234+
`Session#refresh(String entityName, Object object)`::
235+
Removed in favor of `Session#refresh(Object object)`
236+
`Session#refresh(String entityName, Object object, LockOptions lockOptions)`::
237+
Removed in favor of `Session#refresh(Object object, LockOptions lockOptions)`
238+
239+
[[session-save-update]]
240+
=== Session#save, Session#update, Session#saveOrUpdate
241+
242+
All forms of `Session#save`, `Session#update`, `Session#saveOrUpdate` have been removed. See the discussion at <<flush-persist>>.
243+
244+
`Session#save`::
245+
Removed in favor of `Session#persist`.
246+
`Session#update`::
247+
Removed in favor of `Session#merge`
248+
`Session#saveOrUpdate`::
249+
Removed in favor `#persist` if the entity is transient or `#merge` if the entity is detached
250+
251+
Relatedly, `org.hibernate.annotations.CascadeType#SAVE_UPDATE` has been removed in favor of `org.hibernate.annotations.CascadeType#PERSIST` and/or `org.hibernate.annotations.CascadeType#MERGE`
252+
253+
254+
[[session-delete]]
255+
=== Session#delete
256+
257+
`Session#delete` methods has been removed in favor of `Session#remove` (via `EntityManager`). Relatedly, `org.hibernate.annotations.CascadeType#DELETE` was removed in favor of `org.hibernate.annotations.CascadeType#REMOVE`
258+
259+
[[metamodel]]
260+
=== Metamodel
261+
262+
`org.hibernate.Metamodel` has been removed in favor of `org.hibernate.metamodel.model.domain.JpaMetamodel`
263+
264+
265+
[[session-by-natural-id]]
266+
=== Session#byNaturalId
267+
268+
Both `NaturalIdLoadAccess#using(Map)` and `NaturalIdMultiLoadAccess#compoundValue()` have been removed in favor of `Map#of()`
269+
270+
271+
[[removal-annotations]]
272+
=== Annotations
273+
274+
* Removed `@Persister`
275+
* Removed `@Proxy` - see <<proxy-annotation>>
276+
* Removed `@SelectBeforeUpdate` - see <<flush-persist>>
277+
* Removed `@DynamicInsert#value` and `@DynamicUpdate#value` - usage indicates true
278+
* Removed `@Loader`
279+
* Removed `@Table` -> use JPA `@Table`
280+
* Removed `@Where` and `@WhereJoinTable` -> use `@SQLRestriction` or `@SQLJoinTableRestriction`
281+
* Removed `@OrderBy` -> use `@SQLOrder` or JPA `@OrderBy`
282+
* Removed `@ForeignKey` -> use JPA `@ForeignKey`
283+
* Removed `@Index` -> use JPA `@Index`
284+
* Removed `@IndexColumn` -> use JPA `@OrderColumn`
285+
* Removed `@GeneratorType` (and `GenerationTime`, etc)
286+
* Removed `@LazyToOne`
287+
* Removed `@LazyCollection`
288+
* Replaced uses of `CacheModeType` with `CacheMode`
289+
* Removed `@Cache#include` -> use `@Cache#includeLazy`
290+
* Removed `@TestForIssue` (for testing purposes) -> use `org.hibernate.testing.orm.junit.JiraKey` or `org.hibernate.testing.orm.junit.JiraKeyGroup`
291+
292+
293+
[[proxy-annotation]]
294+
=== Replace @Proxy
295+
296+
Applications will need to replace usages of the removed `@Proxy` annotation.
297+
298+
`@Proxy#proxyClass` has no direct replacement, but was also never needed/useful.
299+
300+
Here we focus on `@Proxy#lazy` attribute which, again, was hardly ever useful.
301+
By default (true), Hibernate would proxy an entity when possible and when asked for.
302+
"Asked for" includes calls to `Session#getReference` and lazy associations.
303+
All such cases though are already controllable by the application.
304+
305+
* Instead of `Session#getReference`, use `Session#find`
306+
* Use eager association fetching, for example,
307+
** `FetchType.EAGER` (the default for to-one associations anyway), possibly combined with `@Fetch`,
308+
** `EntityGraph`, or a
309+
** `@FetchProfile`.
310+
311+
The effect can also often be mitigated using Hibernate's bytecode-based laziness (possibly combined with `@ConcreteProxy`).
312+
313+
314+
[[misc-api]]
315+
=== Miscellaneous
316+
317+
* Removed `SqmQualifiedJoin` - all joins are qualified.
318+
* Removed `Session.LockRequest` - use `LockOptions` instead
319+
223320

224321
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225322
// SPI changes
@@ -233,6 +330,37 @@ However, the preferred approach is to explicitly batch operations via `insertMul
233330

234331
The signature of the `Configurable#configure` method changed from accepting just a `ServiceRegistry` instance to the new `GeneratorCreationContext` interface, which exposes a lot more useful information when configuring the generator itself. The old signature has been deprecated for removal, so you should migrate any custom `Configurable` generator implementation to the new one. Or better yet, consider migrating to `@IdGeneratorType`.
235332

333+
[[integrator]]
334+
=== Integrator
335+
336+
The previously deprecated method `org.hibernate.integrator.spi.Integrator#integrate(Metadata,SessionFactoryImplementor,SessionFactoryServiceRegistry)` have been removed in favor of its replacement `org.hibernate.integrator.spi.Integrator#integrate(Metadata,BootstrapContext,SessionFactoryImplementor)`
337+
338+
[[interceptor]]
339+
=== Interceptor
340+
341+
Quite a few (again, previously deprecated) methods on `Interceptor` have been removed in favor of their replacement. This mainly deals with the change in expected Java type of identifiers (done in 6.0) from `Serializable` to `Object`.
342+
343+
* `Interceptor#onLoad`
344+
* `Interceptor#onFlushDirty`
345+
* `Interceptor#onSave`
346+
* `Interceptor#onDelete`
347+
* `Interceptor#onCollectionRecreate`
348+
* `Interceptor#onCollectionRemove`
349+
* `Interceptor#onCollectionUpdate`
350+
* `Interceptor#findDirty`
351+
* `Interceptor#getEntity`
352+
353+
Additionally, `EmptyInterceptor` was removed. As `org.hibernate.Interceptor` now uses default methods, one can simply implement `Interceptor` to the same end.
354+
355+
356+
[[misc-spi]]
357+
=== Miscellaneous
358+
359+
* `org.hibernate.metamodel.spi.MetamodelImplementor`
360+
was removed in favor of `org.hibernate.metamodela.MappingMetmodel` or `org.hibernate.metamodel.model.domain.JpaMetamodel`
361+
* Removed `AdditionalJaxbMappingProducer` in favor of `AdditionalMappingContributor`.
362+
* Removed `MetadataContributor` in favor of `AdditionalMappingContributor`
363+
236364

237365
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
238366
// Changes in Behavior
@@ -571,109 +699,20 @@ However, MySQL treats a `char(1)` containing a single space as an empty string,
571699
Now, `varchar(1)` is used by default.
572700

573701

574-
575-
576-
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
577-
// Removals
578-
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
579-
580-
[[removals]]
581-
== Removals
582-
583-
As this is a major release, a few things have been removed.
584-
585-
[[removal-annotations]]
586-
=== Annotations
587-
588-
* Removed `@Persister`
589-
* Removed `@Proxy` - see <<proxy-annotation>>
590-
* Removed `@SelectBeforeUpdate` - see <<flush-persist>>
591-
* Removed `@DynamicInsert#value` and `@DynamicUpdate#value`
592-
* Removed `@Loader`
593-
* Removed `@Table` -> use JPA `@Table`
594-
* Removed `@Where` and `@WhereJoinTable` -> use `@SQLRestriction` or `@SQLJoinTableRestriction`
595-
* Removed `@OrderBy` -> use `@SQLOrder` or JPA `@OrderBy`
596-
* Removed `@ForeignKey` -> use JPA `@ForeignKey`
597-
* Removed `@Index` -> use JPA `@Index`
598-
* Removed `@IndexColumn` -> use JPA `@OrderColumn`
599-
* Removed `@GeneratorType` (and `GenerationTime`, etc)
600-
* Removed `@LazyToOne`
601-
* Removed `@LazyCollection`
602-
* Replaced uses of `CacheModeType` with `CacheMode`
603-
* Removed `@Cache.include` -> use `@Cache.includeLazy`
604-
* Removed `@TestForIssue` (for testing purposes) -> use `org.hibernate.testing.orm.junit.JiraKey` and `org.hibernate.testing.orm.junit.JiraKeyGroup`
605-
606-
[[removal-classes]]
607-
=== Classes/interfaces
608-
609-
* Removed `SqmQualifiedJoin` (all joins are qualified)
610-
* Removed `AdditionalJaxbMappingProducer` -> `AdditionalMappingContributor`
611-
* Removed `MetadataContributor` -> `AdditionalMappingContributor`
612-
* Removed `EmptyInterceptor` -> implement `org.hibernate.Interceptor` directly
613-
* Removed `Session.LockRequest` -> use `LockOptions`
614-
* See also,
615-
616-
[[removal-methods]]
617-
=== Methods
618-
619-
* Removed code related to save, update and saveOrUpdate - see <<flush-persist>>:
620-
** Removed `Session.save` in favor of `Session.persist`
621-
** Removed `Session.saveOrUpdate` in favor `persist` if the entity is transient or `merge` if the entity is detached
622-
** Removed `Session.update` in favor of `Session.merge`
623-
** Removed `org.hibernate.annotations.CascadeType.SAVE_UPDATE` in favor of `org.hibernate.annotations.CascadeType.PERSIST` + `org.hibernate.annotations.CascadeType.MERGE`
624-
625-
* Removed `Session.delete` in favor of `Session.remove`
626-
* Removed `org.hibernate.annotations.CascadeType.DELETE` in favor of `org.hibernate.annotations.CascadeType.REMOVE`
627-
* Removed `Session.load` in favor of `Session.find`
628-
* Removed `Session.refresh(String entityName, Object object)` in favor of `Session.refresh(Object object)`
629-
* Removed `Session.refresh(String entityName, Object object, LockOptions lockOptions)` in favor of `Session.refresh(Object object, LockOptions lockOptions)`
630-
* Removed `org.hibernate.integrator.spi.Integrator.integrate(Metadata,SessionFactoryImplementor,SessionFactoryServiceRegistry)` in favor of `org.hibernate.integrator.spi.Integrator.integrate(Metadata,BootstrapContext,SessionFactoryImplementor)`
631-
* Removed quite a few deprecated `Interceptor` in favor of their replacements:
632-
** Removed `Interceptor.onLoad(Object, Serializable, Object[] , String[] , Type[] )` in favour of `Interceptor.onLoad(Object, Object, Object[], String[], Type[] )`
633-
** Removed `Interceptor.onFlushDirty(Object, Serializable, Object[] , Object[], String[] , Type[] )` in favour of `Interceptor.onLoad(Object, Object, Object[], Object[], String[] , Type[] )`
634-
** Removed `Interceptor.onSave(Object, Serializable, Object[], String[], Type[])` in favour of `Interceptor.onSave(Object, Object, Object[], String[], Type[])`
635-
** Removed `Interceptor.onDelete(Object, Serializable, Object[], String[], Type[])` in favour of `Interceptor.onDelete(Object, Serializable, Object[], String[], Type[])`
636-
** Removed `Interceptor.onCollectionRecreate(Object, Serializable)` in favour of `Interceptor.onCollectionRecreate(Object, Object)`
637-
** Removed `Interceptor.onCollectionRemove(Object, Serializable)` in favour of `Interceptor.onCollectionRemove(Object, Object)`
638-
** Removed `Interceptor.onCollectionUpdate(Object, Serializable)` in favour of `Interceptor.onCollectionUpdate(Object, Object)`
639-
** Removed `Interceptor.findDirty(Object, Serializable, Object[], Object[], String[], Type[])` in favour of `Interceptor.findDirty(Object, Object, Object[], Object[], String[], Type[])`
640-
** Removed `Interceptor.getEntity(String, Serializable)` in favour of `Interceptor.getEntity(String, Serializable)`
641-
* Removed `org.hibernate.metamodel.spi.MetamodelImplementor` in favor of `org.hibernate.metamodela.MappingMetmodel` or `org.hibernate.metamodel.model.domain.JpaMetamodel`
642-
* Removed `org.hibernate.Metamodel` in favor of `org.hibernate.metamodel.model.domain.JpaMetamodel`
643-
* Removed `NaturalIdLoadAccess.using(Map)` and `NaturalIdMultiLoadAccess.compoundValue()` in favor of `Map.of()`
644-
645-
=== Settings
702+
[[settings]]
703+
=== Changes Related to Settings
646704

647705
* Removed `hibernate.mapping.precedence` and friends
648706
* Removed `hibernate.allow_refresh_detached_entity`
649707

650708

651-
[[proxy-annotation]]
652-
=== Replace @Proxy
653-
654-
Applications will need to replace usages of the removed `@Proxy` annotation.
655-
656-
`@Proxy#proxyClass` has no direct replacement, but was also never needed/useful.
657-
658-
Here we focus on `@Proxy#lazy` attribute which, again, was hardly ever useful.
659-
By default (true), Hibernate would proxy an entity when possible and when asked for.
660-
"Asked for" includes calls to `Session#getReference` and lazy associations.
661-
All such cases though are already controllable by the application.
662-
663-
* Instead of `Session#getReference`, use `Session#find`
664-
* Use eager association fetching, for example,
665-
** `FetchType.EAGER` (the default for to-one associations anyway), possibly combined with `@Fetch`,
666-
** `EntityGraph`, or a
667-
** `@FetchProfile`.
668-
669-
The effect can also often be mitigated using Hibernate's bytecode-based laziness (possibly combined with `@ConcreteProxy`).
670709

671710
[[pools]]
672-
=== Connection Pools
711+
== Connection Pools
673712

674713
Since Vibur and Proxool are no longer actively developed, support for these connection pools was removed.
675714

676715
As part of the effort to relicense, it also became necessary to drop support for UCP connection pool.
677716

678-
Use Agroal or HikariCP instead.
717+
We recommend using Agroal or HikariCP instead; or implement the `ConnectionProvider` yourself to integrate with the Connection Pool of your choice (in fact other Connection Pools are known to ship implementations of the Hibernate `ConnectionProvider` already).
679718

0 commit comments

Comments
 (0)