From 31d5f81d6f24819571402f2782097db2602a5748 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Fri, 10 Apr 2026 15:34:46 -0500 Subject: [PATCH 1/3] 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/3] 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/3] 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.