9.4.6 Separate and merge operations of an entity from the persistence context
An entity separated from the persistence context is called a detached entity. The entity state becomes detached at the following times:
-
When a transaction in the persistence context of the transaction scope is committed
-
When a transaction is rolled back
-
When the persistence context is cleared (when EntityManager.clear() is invoked)
-
When EntityManager is closed
-
When the entity is serialized and the entity value is passed
The instance of the separated entity continues to exist outside the persistence context that is perpetuated and obtained. The states of the entity and the database are not synchronized.
- Organization of this subsection
(1) Accessing a detached entity
An application can access the detached entity even after the persistence context ends. In this case, the entity fields and relation destinations must already be fetched. The fields and the relation destination entities that are not fetched by the detached entity cannot be accessed. Note that FetchType.EAGER is always applied to @Basic specified in the field, so the relation destination entity and field information are already obtained.
To access a relationship from the detached entity, one of the following conditions must be satisfied:
-
The entity instance is obtained using find()
-
The entity is obtained by using a query or the entity is explicitly requested using the FETCH JOIN clause
-
The persistence instance that is not a primary key is already accessed with the application
-
The entity is already obtained from another valid entity by tracing the relation specified as fetch=EAGER
If unavailable instances are accessed and if available instances are accessed in a disabled state, an exception occurs. However, when FetchType.LAZY is specified with Cosminexus JPA Provider, if you access un-fetched fields and relation destination entities even if the entity is detached after EntityManager terminates, sometimes the value is obtained from the database and the contents can be referenced.
(2) merge processing of an entity
By invoking the merge method of EntityManager or by cascading the merge processing, you can merge the detached entity with the persistence context managed by EntityManager.
The following table describes the transition of entity states in the merge processing for each state of entity A.
|
State of entity A |
Results of state transition |
|---|---|
|
new |
A new entity A' is created with managed state and the state of entity A is copied to entity A'. Note that the entity of the merge argument remains new. |
|
managed |
The merge operation is ignored. However, if MERGE or ALL is specified in the cascade attribute for the relationship from entity A to other entities, the merge operation is propagated to the entities referenced by entity A. |
|
detached |
The state of entity A is copied to entity A' that has the same ID and already exists and is being managed, or a new managed entity is created that is a copy of entity A. Note that the entity of the merge argument remains detached. |
|
removed |
IllegalArgumentException is thrown by the merge operation, or transaction commit fails. Note that the state of entity A remains removed. |
Note 1: If the relation from entity A to entity B is specified with cascade=MERGE or cascade=ALL, all the entity B are recursively merged as entity B'. Entity B' is set in entity A'. Note that if entity A is in the managed state, entity A and entity A' are the same.
Note 2: If entity B is referenced when cascade=MERGE or cascade=ALL is not specified in the relation of entity A, when entity A is merged with entity A' and if you trace the relation from entity A', you will finally reach the reference of the managed entity B' with the same persistence identity as entity B.
With the JPA specifications, the fields marked as LAZY to imply that the field is not fetched, are ignored during merge. However, with Cosminexus JPA Provider, @Basic operates as EAGER, therefore, all the fields that are not relationships are subject to the merge processing.
Also, if the Version string is used in the entity, the version of the entity is checked during the merge operation and during the flush and commit processing invoked after the merge operation. If the Version string does not exist, the version of the entity is not checked with the merge operation. For details, see 9.10.1 Optimistic lock processing.
Note that Cosminexus JPA Provider does not support the processing to return to the persistence context using the entity merge processing between vendors.
(3) Notes
-
In Cosminexus JPA Provider, the managed entity becomes a detached entity due to transaction commit with the persistence context of the transaction scope. On the other hand, with the extended persistence context, the managed entity remains managed.
-
If the transaction is rolled back in the transaction scope and in the extended persistence context, all the existing managed instances and removed instances become detached. The state of the instance is the state existing when the transaction is rolled back.
-
If the transaction is rolled back, the state of the persistence context becomes the state existing at rollback, so the state conflicts with the database state. Note that in Cosminexus JPA Provider, the version attribute state and the generated state form conflicting states, therefore, if the merge operation is performed, an exception might occur.