You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by ja...@apache.org on 2026/06/18 19:53:36 UTC
(grails-core) 05/05: Update Hibernate 7 review guidance docs
This is an automated email from the ASF dual-hosted git repository.
jamesfredley pushed a commit to branch 8.0.x-hibernate7
in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit c72941622842ed8368913db2f88faa5c1b9339b6
Author: James Fredley <ja...@users.noreply.github.com>
AuthorDate: Thu Jun 18 15:51:39 2026 -0400
Update Hibernate 7 review guidance docs
Assisted-by: opencode:gpt-5.5
---
.agents/skills/hibernate-developer/SKILL.md | 6 +++---
grails-data-hibernate7/README.md | 21 ++++++++++-----------
grails-doc/src/en/guide/upgrading/upgrading80x.adoc | 4 ++--
3 files changed, 15 insertions(+), 16 deletions(-)
diff --git a/.agents/skills/hibernate-developer/SKILL.md b/.agents/skills/hibernate-developer/SKILL.md
index 37899f949f..052ff2f06c 100644
--- a/.agents/skills/hibernate-developer/SKILL.md
+++ b/.agents/skills/hibernate-developer/SKILL.md
@@ -14,7 +14,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more contributor l
- Provide repository-specific guidance for the `grails-data-hibernate7` project.
- Help with Hibernate 7 migration work in domain binding, mapping metadata, identifiers, generators, collections, and second-pass binding.
- Guide changes around `GrailsDomainBinder`, `GrailsPropertyBinder`, `IdentityBinder`, `VersionBinder`, collection binders, and related utilities.
-- Keep changes aligned with the testing constraints and migration status documented in `grails-data-hibernate7/AGENTS.md`.
+- Keep changes aligned with the testing constraints and migration status used by the Hibernate 7 modules in this repository.
## When to Use Me
@@ -90,7 +90,7 @@ When touching `grails-data-hibernate7`, test through real Hibernate wiring rathe
- Use `HibernateGormDatastoreSpec` for Hibernate 7 integration and domain-binding specifications.
- Prefer `manager.registerDomainClasses(...)` in `setupSpec()` to register entities for specs.
- Define test entities as top-level classes in the same Groovy spec file.
-- Ensure test domain class names are globally unique within the package to avoid collisions during parallel execution.
+- Ensure test domain class names are globally unique within the package to avoid shared mapping metadata collisions when specs run in parallel.
- Prefer real entities over heavy mocking for binder logic.
## Change Workflow
@@ -116,4 +116,4 @@ When touching `grails-data-hibernate7`, test through real Hibernate wiring rathe
## Source of Truth
-This skill is derived from `grails-data-hibernate7/AGENTS.md`. When the module guidance changes, update this skill so agents can load the same rules directly from `.agents/skills/hibernate-developer/SKILL.md`.
+This skill is the repository guidance for Hibernate 7 module work. When module conventions change, update this skill directly so agents load the current rules from `.agents/skills/hibernate-developer/SKILL.md`.
diff --git a/grails-data-hibernate7/README.md b/grails-data-hibernate7/README.md
index 4196706045..2f75b2e58f 100644
--- a/grails-data-hibernate7/README.md
+++ b/grails-data-hibernate7/README.md
@@ -16,16 +16,20 @@
specific language governing permissions and limitations
under the License.
-->
+
# GORM for Hibernate 7
-This project implements [GORM](https://gorm.grails.org) for the Hibernate 7.
-With the removal of Criterion API in Hibernate 7, we wanted to continue to support the DetachedCriteia in GORM as much as possible. We also wanted to encapsulate the JPA Criteria Building in one class so the following was done:
-* DetachedCriteria holds almost all the state of the Query being built. It hold the target class for the query. It does not hold a session.
+This project implements [GORM](https://gorm.grails.org) for Hibernate 7.
+
+With the removal of the Criteria API in Hibernate 7, we wanted to continue to support the DetachedCriteria in GORM as much as possible. We also wanted to encapsulate the JPA Criteria Building in one class so the following was done:
+
+* DetachedCriteria holds almost all the state of the Query being built. It holds the target class for the query. It does not hold a session.
* HibernateQuery has a session and holds the DetachedCriteria and is a thin wrapper for it. Calling list or singleResult will internally create the Query and execute it.
* HibernateCriteriaBuilder is a thin wrapper around HibernateQuery. Its main function is to use closures to populate the Hibernate Query and execute it at the end of the closure.
-* Only the grails-datastore-gorm-hibernate7 module is being developed at the time.
+* The core Hibernate 7 implementation is split across the modules listed below.
For testing the following was done:
+
* Used testcontainers for specific tests instead of h2 to verify features not supported by h2.
* A more opinionated and fluent HibernateGormDatastoreSpec is used for the specifications.
@@ -34,8 +38,8 @@ For testing the following was done:
| Module | Description |
|---|---|
| `grails-data-hibernate7-core` | Domain binding pipeline, GORM/Hibernate mapping, `HibernateDatastore` |
-| `grails-data-hibernate7-spring-orm` | Shared Spring ORM / Hibernate integration support used by the core, boot-plugin, and Grails plugin modules |
-| `grails-data-hibernate7-boot-plugin` | Spring Boot autoconfiguration (`HibernateGormAutoConfiguration`) and Grails CLI SPI (`GormCompilerAutoConfiguration`) |
+| `grails-data-hibernate7-spring-orm` | Shared Spring ORM / Hibernate integration support used by the core, Spring Boot, and Grails plugin modules |
+| `grails-data-hibernate7-spring-boot` | Spring Boot autoconfiguration (`HibernateGormAutoConfiguration`) and Grails CLI SPI (`GormCompilerAutoConfiguration`) |
## Autoconfiguration
@@ -91,8 +95,3 @@ The `grails-data-hibernate7-core` module has minimal coupling to the Grails fram
1. Add BOM coordinates, Javadoc/sources JARs, and POM metadata for Maven Central publication
2. Write integration tests validating end-to-end use from a plain Spring Boot app
-
-
-
-
-
diff --git a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc
index 655cbfe562..2bb92473b3 100644
--- a/grails-doc/src/en/guide/upgrading/upgrading80x.adoc
+++ b/grails-doc/src/en/guide/upgrading/upgrading80x.adoc
@@ -136,7 +136,7 @@ spring:
==== 5. Hibernate ORM Package Relocations
Spring Framework 7 removed the `org.springframework.orm.hibernate5` package entirely.
-Grails 8 vendors these classes from Spring Framework 6.2.x into two new modules — one per supported Hibernate version — so that both Hibernate 5 and Hibernate 7 users have a drop-in replacement.
+Grails 8 vendors these classes from Spring Framework 6.2.x into `grails-data-hibernate5-spring-orm` and `grails-data-hibernate7-spring-orm` so that both Hibernate 5 and Hibernate 7 users have a drop-in replacement.
This change is transparent for most applications since Grails manages the Hibernate integration internally.
However, if your application directly imports any of the following classes, you must update your import statements based on which Hibernate version you are using.
@@ -1094,7 +1094,7 @@ Persisting a transient entity that has detached associations now throws `EntityE
If your domain mapping or annotated classes used `cascade = CascadeType.SAVE_UPDATE`, replace it with `cascade = CascadeType.ALL` or `cascade = [CascadeType.PERSIST, CascadeType.MERGE]` as appropriate.
-Also note that automatic `cascade=PERSIST` on `@Id` and `@MapsId` associations was removed.
+Also note that automatic `cascade = PERSIST` on `@Id` and `@MapsId` associations was removed.
If you relied on this implicit behaviour, add an explicit `cascade = CascadeType.PERSIST` to the `@ManyToOne` or `@OneToOne` carrying `@MapsId`.
===== 26.4 Detached Entity Operations