Skip to content

Some clarifications on stateful repositories around persistence context #1421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
njr-11 wants to merge 3 commits into
base: main
Choose a base branch
from
+4 −4
Open

Some clarifications on stateful repositories around persistence context #1421

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
31d5f81
Avoid implying that a repository only uses one persistence context
njr-11 Apr 10, 2026
4260442
Guarantee persistence context within a transaction
njr-11 Apr 10, 2026
294ba54
Redo changes per Gavin's review comment focus on the association bein…
njr-11 Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions spec/src/main/asciidoc/repository.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -999,7 +999,7 @@ 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.
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.

Expand All @@ -1009,7 +1009,7 @@ A stateful repository is backed by a _persistence context_, a set of managed ent

- 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 the persistence context in which the repository operation is running.

[WARNING]
====
Expand All @@ -1020,7 +1020,7 @@ This specification does not define the lifecycle of a persistence context, nor h

[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.
====

Expand All @@ -1031,7 +1031,7 @@ A <<Lifecycle methods, lifecycle method>> 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 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
Expand Down