Improve Javadoc about OptimisticLockException

[quaff]

No description provided.

[gavinking]

Note sure what this is trying to say.

[quaff]

I changed it to

     * <p>Note that {@link OptimisticLockException} may not be thrown by this
     * method but defer to database synchronization operation.

[gavinking]

So I believe—but I'm not sure, without digging more deeply—that we actually permit the provider to throw OptimisticLockException synchronously from persist() or remove(). Usually that happens from flush() but I think the provider has freedom here.

[quaff]

So I believe—but I'm not sure, without digging more deeply—that we actually permit the provider to throw OptimisticLockException synchronously from persist() or remove(). Usually that happens from flush() but I think the provider has freedom here.

Unlike stateless entity manager, for stateful entity manager, there is no database interaction until flush, remove() doesn't know the entity is stale.
And I don't understand why persist() would cause OptimisticLockException.

[gavinking]

for stateful entity manager, there is no database interaction until flush, remove() doesn't know the entity is stale.

That is one possible implementation, sure. But what the spec actually says is stuff like:

The entity X will be entered into the database at or before transaction commit or as a result of the flush operation.

A removed entity X will be removed from the database at or before transaction commit or as a result of the flush operation.

The persistence provider runtime is permitted to perform synchronization to the database at other times as well when a transaction is active and the persistence context is joined to the transaction.

And of course, it's definitely the case that synchronization can happen when Query.getResultList() is called.

So optimistic lock failures can in principle happen at lots of other moments, not only in the ones you've listed here.