improvements to the migration guide

Author: gavinking

migration-guide.adoc

@@ -56,7 +56,7 @@ This required a few actions on our part:
 
 * Type parameters:
   ** Affects much of the Criteria API - especially roots, joins, paths
-  ** Affects much of the Graph API - see <<load-fetch-graphs>> for details.
+  ** Affects much of the Entity Graph API - see <<load-fetch-graphs>> for details.
 * 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
@@ -107,13 +107,13 @@ See the link:{user-guide-url}#soft-delete[User Guide] for details.
 [[embedded-column-naming]]
 === @EmbeddedColumnNaming
 
-A long requested feature for both Hibernate and Jakarta Persistence has been the ability to
+A long-requested feature for both Hibernate and Jakarta Persistence has been the ability to
 define a prefix for the names of columns associated with an embedded value.
 
 7.0 adds support for this using the new `@EmbeddedColumnNaming` annotation.  The annotation
 accepts a format pattern, so is a little more flexible than just a prefix.
 
-Consider a typical Person / Address composition:
+Consider a typical `Person` / `Address` composition:
 
 [source,java]
 ----
@@ -139,7 +139,7 @@ class Person {
 }
 ----
 
-This triggers Hibernate to use the column names `home_street`, `home_city`, `work_street`, ...
+This instructs Hibernate to use the column names `home_street`, `home_city`, `work_street`, and so on.
 
 See the link:{user-guide-url}#embeddable-column-naming[User Guide] for details.
 
@@ -177,10 +177,10 @@ by asking the converter to convert all the enum constants on start up.
 Hibernate's legacy `hbm.xml` mapping schema has been deprecated for quite some time, replaced by a new `mapping.xml`
 schema.  In 7.0, this `mapping.xml` is stabilized and we now offer a transformation of `hbm.xml` files into `mapping.xml` files.
 
-This tool is available as both -
+This tool is available as both:
 
-* build-time transformation (currently only offered as a Gradle plugin)
-* run-time transformation, using `hibernate.transform_hbm_xml.enabled=true`
+* a build-time transformation (currently only offered as a Gradle plugin), or
+* a runtime transformation, using `hibernate.transform_hbm_xml.enabled=true`
 
 Build-time transformation is preferred.
 
@@ -227,6 +227,12 @@ The new operation `Session.getManagedEntities()` allows the application program
 
 Setting `jakarta.persistence.schema-generation.database.action=populate` or calling `SchemaManager.populate()` populates an existing schema with initial data in `/import.sql` or other SQL scripts specified via `jakarta.persistence.sql-load-script-source`.
 
+[[transaction-api]]
+=== Improvements to Transaction
+
+The `Transaction` interface leaks the SPI type `TransactionStatus` via `getStatus()`, and the JTA-defined type `Synchronization` via `registerSynchronization()`, which breaks layering in a fairly harmless way.
+New operations were added to the `Transaction` interface, allowing code to inspect the status of the transaction or register callbacks without the use of layer-breaking operations.
+
 
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 // API changes
@@ -242,7 +248,11 @@ A general theme in 7.0 has been to remove Hibernate-specific features that have
 
 `Session#load` methods have been removed in favor of `Session#getReference` which have the same semantic.
 
-NOTE: `Session#get` was not previously deprecated as `Session#load` was, so it was not appropriate to remove.  Starting in 7.0, `Session#get` is considered deprecated, to be removed in 8.0.  Per the deprecation notes, use `Session#find` instead.
+[[session-get]]
+=== Session#get
+`Session#get` methods were deprecated in favor of the JPA-standard `Session#find`, and new overloads of `Session#find` were added.
+
+NOTE: `Session#get` was not previously deprecated as `Session#load` was, so it was not appropriate to remove it.
 
 [[session-refresh]]
 === Session#refresh
@@ -336,6 +346,13 @@ All such cases though are already controllable by the application.
 
 The effect can also often be mitigated using Hibernate's bytecode-based laziness (possibly combined with `@ConcreteProxy`).
 
+[[usertype]]
+=== Changes to UserType and CompositeUserType
+
+The API interfaces `UserType` and `CompositeUserType` leaked the SPI types `SharedSessionContractImplementor` and `SessionFactoryImplementor`, which was a layer-breaker.
+
+The solution was to change the signature of `nullSafeSet()` and `nullSafeGet()` in `UserType` via deprecation of the previous declarations, and remove some unnecessary parameters from methods of the incubating interface `CompositeUserType`.
+
 
 [[misc-api]]
 === Miscellaneous
@@ -344,6 +361,8 @@ The effect can also often be mitigated using Hibernate's bytecode-based laziness
 * Removed `SqmQualifiedJoin` - all joins are qualified.
 * Both `NaturalIdLoadAccess#using(Map)` and `NaturalIdMultiLoadAccess#compoundValue()` have been removed in favor of `Map#of()`
 * Removed `Session.LockRequest` - use `LockOptions` instead
+* `SessionFactory.createEntityManager()` now returns `Session` for convenience
+* `CommonQueryContract.setFlushMode()` was deprecated in favor of `setQueryFlushMode` accepting a `QueryFlushMode`
 
 
 
@@ -390,6 +409,12 @@ was removed in favor of `org.hibernate.metamodel.MappingMetmodel` or `org.hibern
 * Removed `AdditionalJaxbMappingProducer` in favor of `AdditionalMappingContributor`.
 * Removed `MetadataContributor` in favor of `AdditionalMappingContributor`
 
+[[jfr-spi]]
+=== JFR SPI
+
+The types `EventMonitor` and `DiagonosticEvent` replace the now-deprecated SPIs `EventManager` and `HibernateMonitoringEvent` use for integration with Java Flight Recorder.
+
+Hibernate now reports many more kinds of `DiagnosticEvent` to JFR.
 
 
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -496,17 +521,18 @@ or:
 
 [source,java]
 List query =
-        session.createQuery("from X join y")
+        session.createQuery("from X join ys")
                 .getResultList()
 
 The select list was inferred based on the `from` clause.
 
 In Hibernate 6 we decided to deprecate this overload of `createQuery()`, since:
 
-- it returns a raw type, resulting in compiler warnings in client code, and
+- it returns a raw type `Query`, resulting in compiler warnings in client code,
+- each query result must be explicitly cast from `Object` to the query result type, and
 - the second query is truly ambiguous, with no obviously intuitive interpretation.
 
-As of Hibernate 7, the method is remains deprecated, and potentially-ambiguous queries _are no longer accepted_.
+As of Hibernate 7, the method remains deprecated, and potentially-ambiguous queries _are no longer accepted_.
 Migration paths include:
 
 1. explicitly specify the `select` list,
@@ -524,17 +550,21 @@ or:
 
 [source,java]
 List<X> result =
-        session.createQuery("from X join y", X.class)
+        session.createQuery("from X join ys", X.class)
                 .getResultList()
 
 [[flush-persist]]
 === Session flush and persist
 
-The removal of `CascadeType.SAVE_UPDATE` slightly changes the persist and flush behaviour to conform with Jakarta Persistence.
+The removal of `CascadeType.SAVE_UPDATE` slightly changes the persist and flush behaviour to conform with the Jakarta Persistence specification.
+
+Making a transient entity persistent or flushing a managed entity now results in an `jakarta.persistence.EntityExistsException` if:
 
-Persisting a transient entity or flushing a manged entity with an associated detached entity having the association annotated with `cascade = CascadeType.ALL` or `cascade = CascadeType.PERSIST` throws now an `jakarta.persistence.EntityExistsException` if the detached entity has not been re-associated with the Session.
+- the entity has an association with `cascade = CascadeType.ALL` or `cascade = CascadeType.PERSIST`, and
+- the association references a detached instance of the associated entity class.
 
-To re-associate the detached entity with the Session the `Session#merge` method can be used.
+To avoid this exception, the reference to the detached instance should be replaced with a reference to a managed instance associated with the current session.
+Such a reference may be obtained by calling `merge()` or `getReference()` on the detached entity instance.
 
 Consider the following model
 
@@ -567,7 +597,7 @@ Assuming we have `c1` as a detached `Child`, the following code will now result
 
 [source,java]
 ----
-Parent parent = session.get( Parent.class, parentId );
+Parent parent = session.find( Parent.class, parentId );
 parent.addChild( c1 );
 ----
 
@@ -576,7 +606,7 @@ Instead, `c1` must first be re-associated with the Session using merge:
 
 [source,java]
 ----
-Parent parent = session.get( Parent.class, parentId );
+Parent parent = session.find( Parent.class, parentId );
 Child merged = session.merge( c1 );
 parent.addChild( merged );
 ----
@@ -734,7 +764,9 @@ Now, `varchar(1)` is used by default.
 
 Since Vibur and Proxool are no longer actively developed, support for these connection pools was removed.
 
-As part of the effort to relicense, it also became necessary to drop support for UCP connection pool.
+As part of the effort to relicense Hibernate, it also became necessary to drop support for Oracle UCP connection pool.
 
-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).
+We recommend using https://github.com/agroal/agroal[Agroal] or https://github.com/brettwooldridge/HikariCP[HikariCP] instead.
+Alternatively, you may implement the `ConnectionProvider` interface to integrate the connection pool of your choice.
+In fact, some connection pools already include their own implementations of `ConnectionProvider`.