Some clarifications on stateful repositories around persistence context

[njr-11]

The language we currently have implies in some places there is only one persistence context associated with a repository:

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 lifecycle method annotated @Remove or @Refresh only accepts managed entities associated with the persistence context underlying the repository.

A stateful repository is backed by a persistence context

Methods of a repository can be invoked by multiple threads at the same time. Persistence context is not designed to be accessed by multiple threads or from multiple transactions, as stated in another line from the Data spec

A persistence context is never shared across transactions.

The first 3 references cited above need to be adjusted, which is done in commit 1.

Commit 2 strengthens requirements and guarantees to the developer around using a stateful repository within a transaction.

Usage of a stateless repository outside of a transaction is another problem. Considering the following pattern,

person = people.find(id);
person.setStreetAddress(newAddress);
person.setCity(newCity);
person.setState(newState);

How does the Jakarta Data provider know that the application is done with the persistence context such that updates ought to be flushed to the database versus whether the application intends to make another update,

person.setZipCode(newZipCode);

The only way I know of to indicate this currently is to use a resource accessor method on a JPA-backed Data provider to explicitly flush,

EntityManager em = people.getEntityManager();
em.flush();
em.close(); // ?

Resource accessor methods are an advanced pattern. I also don't like the problem the user is confronted with here of whether it's a good idea or terrible idea to close the EntityManager obtained from the stateful repository. Assuming usage outside of a transaction is intended to be supported -- the Data spec doesn't currently require a transaction -- I think we can make this easier on users by providing a built-in flush() operation. But that will require an interface for StatefulRepository. I haven't included that in this PR because we should probably discuss it first.

[gavinking]

I agree that this could be clarified by saying that the association between persistence context and repository might be scoped to a thread, or to a transaction, or whatever, but I'm not keen on these specific changes.

[gavinking]

All you need to really say is that the association is contextual.

[njr-11]

All you need to really say is that the association is contextual.

Alright, I reduced the scope of this to only cover the first item, to at least avoid the misinterpretation and restate things along those lines.

We can discuss the other other items separately from this PR.