release details

sebersole · sebersole · commit ca8d8b2cc360 · 2025-03-27T08:48:37.000-05:00
diff --git a/migration-guide.adoc b/migration-guide.adoc
@@ -5,6 +5,7 @@
 :versionDocBase: {docsBase}/7.0
 :userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
 :javadocsBase: {versionDocBase}/javadocs
+:releaseSeriesBase: https://hibernate.org/orm/releases/7.0/
 :fn-cascase-type: footnote:cascade-type[`org.hibernate.annotations.Cascade` and `org.hibernate.annotations.CascadeType` are both fully deprecated as of 7.0]
 
 This guide discusses migration to Hibernate ORM version 7.0. For migration from
@@ -44,10 +45,15 @@ This required a few actions on our part:
 [[requirements]]
 == Requirements
 
-* Java 17, or greater
+* <<java-17>>, or greater
 * <<jpa-32>>
 * <<hibernate-models>>
 
+[[java-17]]
+=== Java 17
+
+Hibernate now baselines on Java 17.  Newer Java versions may also be used.
+
 
 [[jpa-32]]
 === Jakarta Persistence 3.2
@@ -70,6 +76,9 @@ This required a few actions on our part:
 
 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.
 
+- https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/24/[TCK Results] with Java 17
+- https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/25/[TCK Results] with Java 21
+
 [[hibernate-models]]
 === Hibernate Models
 
@@ -94,138 +103,8 @@ annotations.  Check out its project page for complete details.
 [[new-features]]
 == New Features
 
-New features introduced in 7.0...
-
-[[soft-delete-timestamp]]
-=== @SoftDelete with TIMESTAMP
-
-Soft-delete now supports the strategy of tracking the timestamp at which the soft-delete occurred,
-in addition to the previous truth-based strategies.
-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
-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:
-
-[source,java]
-----
-@Embeddable
-class Address {
-    String street;
-	String city;
-	...
-}
-
-@Entity
-class Person {
-	...
-
-    @Embedded
-    @EmbeddedColumnNaming("home_%")
-    Address homeAddress;
-
-    @Embedded
-    @EmbeddedColumnNaming("work_%")
-    Address workAddress;
-
-}
-----
-
-This triggers Hibernate to use the column names `home_street`, `home_city`, `work_street`, ...
-
-See the link:{user-guide-url}#embeddable-column-naming[User Guide] for details.
-
-[[NamedEntityGraph]]
-=== @NamedEntityGraph
-
-A new annotation (`@org.hibernate.annotations.NamedEntityGraph`) has been added to allow
-specifying a named entity-graph using Hibernate's ability to parse a string representation of the graph.
-
-
-[source,java]
-----
-@Entity
-@NamedEntityGraph( graph="title, isbn, author( name, phoneNumber )" )
-class Book {
-	// ...
-}
-----
-
-
-See `org.hibernate.graph.GraphParser` for details on the syntax and the
-link:{user-guide-url}#fetching-strategies-dynamic-fetching-entity-graph-parsing-annotation[User Guide] for additional details.
-
-
-[[enum-checks]]
-=== Converted Enums and Check Constraints
-
-Hibernate previously added support for generating check constraints for enums mapped using `@Enumerated`
-as part of schema generation.  7.0 adds the same capability for enums mapped using an `AttributeConverter`,
-by asking the converter to convert all the enum constants on start up.
-
-[[hbm-transform]]
-=== hbm.xml Transformation
+See the link:{releaseSeriesBase}#whats-new[website] for the list of new features in the 7.0 series.
 
-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 -
-
-* build-time transformation (currently only offered as a Gradle plugin)
-* run-time transformation, using `hibernate.transform_hbm_xml.enabled=true`
-
-Build-time transformation is preferred.
-
-[NOTE]
-====
-Initial versions of the transformation processed one file at a time.
-This is now done across the entire set of `hbm.xml` files at once.
-While most users will never see this change, it might impact integrations which tie-in to XML processing.
-====
-
-[[stateless-session-cache]]
-=== StatelessSession and Second Level Cache
-
-Previously, stateless sessions never interacted with the second-level cache.
-This reflected their original intended role in bulk processing.
-With the advent of Jakarta Data and Hibernate Data Repositories, the responsibilities of `StatelessSession` have now expanded, and this behavior is no longer appropriate.
-
-Thus, a stateless session now makes use of the second-level cache by default.
-To completely bypass the second-level cache, recovering the previous behavior, call `setCacheMode(CacheMode.IGNORE)`.
-
-It's often important to explicitly disable puts to the second-level cache in code which performs bulk processing.
-Set the cache mode to `GET` or configure `jakarta.persistence.cache.storeMode` to `BYPASS`.
-
-[[stateless-session-jdbc-batching]]
-=== StatelessSession and JDBC Batching
-
-Automatic JDBC batching has the side effect of delaying the execution of the batched operation, and this undermines the synchronous nature of operations performed through a stateless session.
-In Hibernate 7, the configuration property `hibernate.jdbc.batch_size` now has no effect on a stateless session.
-Automatic batching may be enabled by explicitly calling `setJdbcBatchSize()`.
-However, the preferred approach is to explicitly batch operations via `insertMultiple()`, `updateMultiple()`, or `deleteMultiple()`.
-
-[[session-find-multiple]]
-=== findMultiple()
-
-The new operation `Session.findMultiple()`, along with the `BatchSize` option provides a convenient way to fetch a batch of entities by id.
-
-[[session-managed-entities]]
-=== Direct access to first-level cache
-
-The new operation `Session.getManagedEntities()` allows the application program to iterate over all entities in the first-level cache, or over all entities of a given type.
-
-[[schema-manager-populate]]
-=== Data population
-
-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`.
 
 
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -235,17 +114,22 @@ Setting `jakarta.persistence.schema-generation.database.action=populate` or call
 [[api-changes]]
 == Changes to API
 
+This section describes changes to contracts (classes, interfaces, methods, etc.) which are consider https://hibernate.org/community/compatibility-policy/#api[API].
+
+[[defer-to-jpa]]
+=== Defer to JPA
+
 A general theme in 7.0 has been to remove Hibernate-specific features that have a direct replacement in JPA.
 
 [[session-load]]
-=== Session#load
+==== Session#load
 
 `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-refresh]]
-=== Session#refresh
+==== Session#refresh
 
 The forms of `Session#refresh` accepting an entity-name have been removed; the passed entity already indicates the entity-name (even with dynamic models).
 
@@ -255,7 +139,7 @@ The forms of `Session#refresh` accepting an entity-name have been removed; the p
         Removed in favor of `Session#refresh(Object object, LockOptions lockOptions)`
 
 [[session-save-update]]
-=== Session#save, Session#update, Session#saveOrUpdate
+==== Session#save, Session#update, Session#saveOrUpdate
 
 All forms of `Session#save`, `Session#update`, `Session#saveOrUpdate` have been removed.  See the discussion at <<flush-persist>>.
 
@@ -270,7 +154,7 @@ Relatedly, `org.hibernate.annotations.CascadeType#SAVE_UPDATE` has been removed
 
 
 [[session-delete]]
-=== Session#delete
+==== Session#delete
 
 `Session#delete` methods has been removed in favor of `Session#remove`.  Relatedly, `org.hibernate.annotations.CascadeType#DELETE` was removed in favor of `org.hibernate.annotations.CascadeType#REMOVE`{fn-cascase-type}
 
@@ -354,6 +238,8 @@ The effect can also often be mitigated using Hibernate's bytecode-based laziness
 [[spi-changes]]
 == Changes to SPI
 
+This section describes changes to contracts (classes, interfaces, methods, etc.) which are consider https://hibernate.org/community/compatibility-policy/#spi[SPI].
+
 [[configurable-generators]]
 === Configurable generators
 
@@ -399,6 +285,7 @@ was removed in favor of `org.hibernate.metamodel.MappingMetmodel` or `org.hibern
 [[behavior-changes]]
 == Changes in Behavior
 
+
 [[model-validation]]
 === Domain Model Validations
 
@@ -481,6 +368,29 @@ This includes auto-applied converters.
 To suppress the error for an auto-applied converter, use `@Convert(disableConversion=true)`.
 
 
+[[stateless-session-behavior]]
+=== StatelessSession Behavior
+
+The behavior of Hibernate's `StatelessSession` has changed in 2 specific ways to be aware of:
+
+[[stateless-session-cache]]
+==== StatelessSession and Second-Level Cache
+
+A stateless session now link:{releaseSeriesBase}#stateless-session-cache[makes use of the second-level cache] by default.  This will affect migrating applications using second-level cache and `StatelessSession`.
+
+To completely bypass the second-level cache, recovering the previous behavior, call `setCacheMode(CacheMode.IGNORE)`.
+
+It's often important to explicitly disable puts to the second-level cache in code which performs bulk processing.
+Set the cache mode to `GET` or configure `jakarta.persistence.cache.storeMode` to `BYPASS`.
+
+
+[[stateless-session-jdbc-batching]]
+==== StatelessSession and JDBC Batching
+
+The configuration property `hibernate.jdbc.batch_size` now has link:{releaseSeriesBase}#stateless-session-jdbc-batching[no effect on a StatelessSession].
+JDBC batching may be enabled by explicitly calling `setJdbcBatchSize()`.
+However, the preferred approach is to use the new link:{releaseSeriesBase}#stateless-session-multiple[explicit batch operations] via `insertMultiple()`, `updateMultiple()`, or `deleteMultiple()`.
+
 
 [[create-query]]
 === Query with Implicit SELECT and No Explicit Result Type
@@ -680,6 +590,8 @@ Starting in 7.0, when `ValidationMode#AUTO` is specified and a Bean Validation p
 [[ddl-changes]]
 == Changes Affecting DDL
 
+This section describes changes which may affect the application's database schema.
+
 [[ddl-implicit-datatype-timestamp]]
 === Default Precision for timestamp
 
@@ -732,9 +644,7 @@ Now, `varchar(1)` is used by default.
 [[pools]]
 == Connection Pools
 
-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.
+We have decided to drop built-in support for the Vibur, Proxool and UCP Connection Pools.  This is dues to a variety of reasons, a main one being that we are not able to properly test them.
 
 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).
 
diff --git a/release_notes.md b/release_notes.md
@@ -1,89 +1,3 @@
 
-### <a name="jpa-32"></a> Jakarta Persistence 3.2
-
-7.0 migrates to Jakarta Persistence 3.2 which can be fairly disruptive.
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#jpa-32) for details.
-
-See [this blog post](https://in.relation.to/2024/04/01/jakarta-persistence-3/) for a summary of the changes in 3.2
-
-- [TCK Results](https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/24/) with Java 17
-- [TCK Results](https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/25/) with Java 21
-
-### <a name="java-17"></a> Java 17
-
-Version 3.2 of Jakarta Persistence requires Java 17.  
-Hibernate 7.0 therefore baselines on Java 17 whereas previous versions baseline on Java 11.
-
-### <a name="model-validations"></a> Domain Model Validations
-
-7.0 does much more validation of an application's domain model and especially its mapping details, e.g.
-
-* illegal combinations such as `@Basic` and `@ManyToOne` on the same attribute
-* misplaced annotations such as an annotated getter method with FIELD access
-* stricter following of JavaBean conventions
-
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#model-validation) for details.
-
-
-### <a name="mapping-xml"></a> mapping.xsd
-
-Hibernate 7.0 provides a new XSD that represents an "extension" of the Jakarta Persistence orm.xsd weaving in Hibernate-specific mapping features.  
-The namespace for this extended mapping is `http://www.hibernate.org/xsd/orm/mapping`
-
-For applications using Hibernate's legacy `hbm.xml` format, we provide a tool to help with the transformation.
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#hbm-transform) for details.
-
-
-### <a name="hibernate-models"></a> Hibernate Models
-
-7.0 migrates from [Hibernate Commons Annotations](https://github.com/hibernate/hibernate-commons-annotations/) (HCANN) to the new [Hibernate Models](https://github.com/hibernate/hibernate-models) project for low-level processing of an application domain model, reading annotations and weaving in XML mapping documents.
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#hibernate-models) for details.
-
-
-### <a name="json-and-xml-functions"></a> JSON and XML functions
-
-Support for most of the JSON and XML functions that the SQL standard specifies was added to HQL/Criteria.
-The implementations retain the SQL standard semantics and will throw an error if emulation on a database is impossible.
-
-New functions include:
-
-* construction functions like `json_array()`, `json_object()`, `xmlelement()` and `xmlforest()`
-* query functions like `json_value()`, `json_query()` and `xmlquery()`
-* aggregation functions like `json_agg()`, `json_object_agg()` and `xmlagg()`
-* manipulation functions like `json_set()`, `json_mergepatch()`
-* any many more
-
-> The functions are incubating/tech-preview - to use them in HQL it is necessary to enable the `hibernate.query.hql.json_functions_enabled` and `hibernate.query.hql.xml_functions_enabled` configuration settings.
-
-
-### <a name="set-returning-functions"></a> Set-returning Functions
-
-A set-returning function is a new type of function that can return rows and is exclusive to the `from` clause.
-The concept is known in many different database SQL dialects and is sometimes referred to as table valued function or table function.
-
-Custom set-returning functions can be registered via a `FunctionContributor`.
-Out-of-the-box, some common set-returning functions are already supported or emulated
-
-* `unnest()` - allows to turn an array into rows
-* `generate_series()` - can be used to create a series of values as rows
-* `json_table()` - turns a JSON document into rows
-* `xmltable()` - turns an XML document into rows
-
-### <a name="any-discriminator"></a> @AnyDiscriminatorImplicitValues
-
-The new  `@AnyDiscriminatorImplicitValues` offers 2 related improvements for the mapping of discriminator values
-for `@Any` and `ManyToAny` associations.
-
-First, it allows control over how Hibernate determines the discriminator value to store in the database for
-implicit discriminator mappings.  Historically, Hibernate would always use the full name of the associated
-entity.
-
-Second, it allows mixing of explicit and implicit value strategies.
-
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#associations-any) for details.
-
-### <a name=cleanup"></a> Clean-up
-
-A lot of deprecated contracts and behavior has been removed.
-See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#cleanup) for details.
-
+* See the [website](https://hibernate.org.orm/releases/7.0) for requirements and new features in 7.0.
+* See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html) for details about migration from version 6.6 to 7.0.
