From 31d5f81d6f24819571402f2782097db2602a5748 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Fri, 10 Apr 2026 15:34:46 -0500 Subject: [PATCH 1/5] Avoid implying that a repository only uses one persistence context --- spec/src/main/asciidoc/repository.asciidoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index c936fe364..2fb6f549d 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -999,17 +999,19 @@ Support for stateful repositories is defined in the dedicated module `jakarta.da ==== Persistence contexts -A stateful repository is backed by a _persistence context_, a set of managed entity instances in which at most one instance represents a given record in the database. +Each operation on a stateful repository is associated with a _persistence context_, a set of managed entity instances in which at most one instance represents a given record in the database. - An entity instance never belongs to multiple persistence contexts. - The Jakarta Data implementation must ensure that a given persistence context never contains more than one entity instance representing the same record. -- Multiple repositories might share a persistence context, especially if they share a datastore. +- Multiple operations on a single repository, in particular those running in the same transaction or thread, can share a persistence context. + +- Operations on multiple repositories might share a persistence context, especially if the repositories share a datastore. - A persistence context is never shared across transactions. -A query method of a stateful repository which returns an entity type always returns managed instances belonging to the persistence context associated with the repository. +A query method of a stateful repository which returns an entity type always returns managed instances belonging to a persistence context associated with the repository. [WARNING] ==== @@ -1031,7 +1033,7 @@ A <> of a stateful repository must be annot The annotations `@Save`, `@Insert`, `@Update`, `@Delete` are used to define stateless repositories and must not be used to declare lifecycle methods of a stateful repository. Instead, this specification defines the special lifecycle annotations `@Persist`, `@Merge`, `@Refresh`, `@Remove`, and `@Detach` for declaring lifecycle methods of stateful repositories. -A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities associated with the persistence context underlying the repository. +A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities belonging to a persistence context that is associated with the repository. On the other hand, a method annotated `@Persist`, `@Merge`, or `@Detach` also accepts unmanaged entities. ==== Automatic change detection From 42604424fd2bbab9bd4634426b99d6beea6ec86d Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Fri, 10 Apr 2026 16:11:14 -0500 Subject: [PATCH 2/5] Guarantee persistence context within a transaction --- spec/src/main/asciidoc/repository.asciidoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 2fb6f549d..9cc387e8a 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -1020,9 +1020,13 @@ If an application program accesses an entity instance belonging to a persistence This specification does not define the lifecycle of a persistence context, nor how a persistence context is propagated across repositories. +===== Persistence context within a transaction + +All operations performed on a given repository that participate in a given transaction must run under the same persistence context. The Jakarta Data provider must ensure that the persistence context is flushed prior to or during the before completion phase of transaction commit. + [NOTE] ==== -Implementations of Jakarta Data are encouraged to propagate a single persistence context within a given transaction across repositories which share a given datasource. +Implementations of Jakarta Data are encouraged to propagate a single persistence context within a given transaction across repositories which share a given data store. For example, a Jakarta Data provider backed by an implementation of Jakarta Persistence might take advantage of standard Jakarta EE transaction-scoped persistence context propagation. ==== @@ -1045,7 +1049,7 @@ Invocation of a lifecycle method or modification of the state of a managed entit Such changes to the database do not typically happen synchronously with invocation of the lifecycle method, or immediately after modification of the managed entity. Instead, such changes are made when the persistence context is periodically _flushed_. -NOTE: This specification does not prescribe the timing of flush operations, but a flush typically happens before execution of a query or during the before completion phase of transaction commit. +NOTE: This specification does not prescribe the timing of flush operations for persistence context that does not participate in a transaction. An implementation of Jakarta Data should flush as needed to ensure that query results are consistent with the current state of the persistence context. From 294ba54a07712ad5130caa55c199f04b407c5cfe Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Mon, 13 Apr 2026 10:29:11 -0500 Subject: [PATCH 3/5] Redo changes per Gavin's review comment focus on the association being contextual --- spec/src/main/asciidoc/repository.asciidoc | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 9cc387e8a..8b4ef9c56 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -999,19 +999,17 @@ Support for stateful repositories is defined in the dedicated module `jakarta.da ==== Persistence contexts -Each operation on a stateful repository is associated with a _persistence context_, a set of managed entity instances in which at most one instance represents a given record in the database. +A stateful repository operation applies to a _persistence context_, a set of managed entity instances in which at most one instance represents a given record in the database. Persistence context can span multiple repository operations, such as all operations performed within a transaction. - An entity instance never belongs to multiple persistence contexts. - The Jakarta Data implementation must ensure that a given persistence context never contains more than one entity instance representing the same record. -- Multiple operations on a single repository, in particular those running in the same transaction or thread, can share a persistence context. - -- Operations on multiple repositories might share a persistence context, especially if the repositories share a datastore. +- Multiple repositories might share a persistence context, especially if they share a datastore. - A persistence context is never shared across transactions. -A query method of a stateful repository which returns an entity type always returns managed instances belonging to a persistence context associated with the repository. +A query method of a stateful repository which returns an entity type always returns managed instances belonging to the persistence context in which the repository operation is running. [WARNING] ==== @@ -1020,10 +1018,6 @@ If an application program accesses an entity instance belonging to a persistence This specification does not define the lifecycle of a persistence context, nor how a persistence context is propagated across repositories. -===== Persistence context within a transaction - -All operations performed on a given repository that participate in a given transaction must run under the same persistence context. The Jakarta Data provider must ensure that the persistence context is flushed prior to or during the before completion phase of transaction commit. - [NOTE] ==== Implementations of Jakarta Data are encouraged to propagate a single persistence context within a given transaction across repositories which share a given data store. @@ -1037,7 +1031,7 @@ A <> of a stateful repository must be annot The annotations `@Save`, `@Insert`, `@Update`, `@Delete` are used to define stateless repositories and must not be used to declare lifecycle methods of a stateful repository. Instead, this specification defines the special lifecycle annotations `@Persist`, `@Merge`, `@Refresh`, `@Remove`, and `@Detach` for declaring lifecycle methods of stateful repositories. -A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities belonging to a persistence context that is associated with the repository. +A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities associated with the persistence context under which the repository method is running. On the other hand, a method annotated `@Persist`, `@Merge`, or `@Detach` also accepts unmanaged entities. ==== Automatic change detection @@ -1049,7 +1043,7 @@ Invocation of a lifecycle method or modification of the state of a managed entit Such changes to the database do not typically happen synchronously with invocation of the lifecycle method, or immediately after modification of the managed entity. Instead, such changes are made when the persistence context is periodically _flushed_. -NOTE: This specification does not prescribe the timing of flush operations for persistence context that does not participate in a transaction. +NOTE: This specification does not prescribe the timing of flush operations, but a flush typically happens before execution of a query or during the before completion phase of transaction commit. An implementation of Jakarta Data should flush as needed to ensure that query results are consistent with the current state of the persistence context. From 6245beeac6b1106e5d5b64c6cda3e9ba24fd3341 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Mon, 1 Jun 2026 08:45:19 -0500 Subject: [PATCH 4/5] Apply suggestion from @gavinking Co-authored-by: Gavin King --- spec/src/main/asciidoc/repository.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 8b4ef9c56..ea8f93ab5 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -999,7 +999,9 @@ Support for stateful repositories is defined in the dedicated module `jakarta.da ==== Persistence contexts -A stateful repository operation applies to a _persistence context_, a set of managed entity instances in which at most one instance represents a given record in the database. Persistence context can span multiple repository operations, such as all operations performed within a transaction. +A stateful repository operation is always performed in a _persistence context_, operating on a set of managed entity instances in which at most one instance represents a given record in the database. +A given persistence context might span multiple repository operations. +For example, a persistence context often spans the operations performed within a given transaction. - An entity instance never belongs to multiple persistence contexts. From e86cf66e47aa1a55ef495a35cd0fa69b7229f049 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Mon, 1 Jun 2026 08:46:14 -0500 Subject: [PATCH 5/5] Improvements to wording suggested by Gavin Co-authored-by: Gavin King --- spec/src/main/asciidoc/repository.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index ea8f93ab5..a9598c1ae 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -1011,7 +1011,7 @@ For example, a persistence context often spans the operations performed within a - A persistence context is never shared across transactions. -A query method of a stateful repository which returns an entity type always returns managed instances belonging to the persistence context in which the repository operation is running. +A query method of a stateful repository which returns an entity type always returns managed instances belonging to the persistence context in which the repository operation is performed. [WARNING] ==== @@ -1033,7 +1033,7 @@ A <> of a stateful repository must be annot The annotations `@Save`, `@Insert`, `@Update`, `@Delete` are used to define stateless repositories and must not be used to declare lifecycle methods of a stateful repository. Instead, this specification defines the special lifecycle annotations `@Persist`, `@Merge`, `@Refresh`, `@Remove`, and `@Detach` for declaring lifecycle methods of stateful repositories. -A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities associated with the persistence context under which the repository method is running. +A lifecycle method annotated `@Remove` or `@Refresh` only accepts managed entities associated with the persistence context in which the repository method is performed. On the other hand, a method annotated `@Persist`, `@Merge`, or `@Detach` also accepts unmanaged entities. ==== Automatic change detection