6.4.1 Transition of entity states

An entity has a state. When you perform operations for an entity, the state of the entity changes. This subsection describes the types of entity states, the operations executed for the entity, and the entity operations and state transition.

Organization of this subsection
(1) Types of entity states
(2) Operations for the entities
(3) Operations and state transition for the entities
(4) Propagation of operations to the entities

(1) Types of entity states

An entity has four types of states, namely new, managed, detached, and removed. The entity state is changed by using the EntityManager method to operate an entity.

The following table lists and describes each entity state.

Table 6-4 Entity state

State of entity instancesExplanation
newA state in which the entity is newly generated.
A newly generated entity instance does not have a persistence identity, and is, therefore, not associated with the persistence context.
managedA state in which the entity has a persistence identity associated with the persistence context and is managed with the persistence context.
detachedA state in which the entity has a persistence identity that is not associated with the persistence context.
removedA state in which the entity has a persistence identity and is associated with the persistence context. Also, includes the state in which the entity instance is scheduled for deletion from the database.

(2) Operations for the entities

If the user searches the database records, Cosminexus JPA Provider stores the obtained data in the entity fields. Also, when the user updates the database contents, the entity state is applied to the database by changing the state of the entity registered in the persistence context and by committing the transaction. Thus, by executing operations for the entity, the database information is updated.

The following table lists and describes the types of operations for the entities.

Table 6-5 Types of operations for the entities

OperationsExplanation
flushThis operation applies the content of the entity object to the database.
mergeIn this operation, the entity object that was not managed by EntityManager is managed by EntityManager.
persistThis operation manages and perpetuates the entity object.
refreshThis operation applies the database content to the entity object.
removeThis operation sets the entity object to the state of scheduled deletion.

(3) Operations and state transition for the entities

The following figure shows the operations and the state transition for the entity instances.

Figure 6-3 Operations and state transition for the entity instances

[Figure]

The following table describes the operations and state transition for the entities.

Table 6-6 Transition of entity states

OperationsState
newmanageddetachedremoved
persistmanaged#1managedmanaged#1managed
removenewremovedException#2, #3removed
merge
  • Copy source
    new
  • Copy destination
    managed
  • Copy source
    managed
  • Copy destination
    managed
  • Copy source
    detached
  • Copy destination
    managed
Exception#3, #4
refreshException#2, #4managed#5Exception#2, #4Exception#2, #4
commit--#6--detached
rollback--detached--detached
flush--managed--detached
clear--detached--detached
Legend:
--: Not applicable

#1 If an exception occurs in the persist operation, the state enters the original state without being changed.

#2 The exception that occurs is IllegalArgumentException.

#3 If the corresponding line does not exist in the database, the operation is ignored.

#4 If an exception occurs, the state does not change and remains as the original.

#5 If the corresponding line does not exist in the database, EntityNotFoundException occurs.

#6 For a persistence context in the transaction scope, the state is detached. For an extended persistence context, the state is managed.


Furthermore, the operations when persist, remove, merge, and refresh are executed outside the transaction vary according to the type of the persistence context.

(4) Propagation of operations to the entities

When the entities have a relationship and if you specify the cascade attribute of the annotation indicating the relationship, the operations for the entity are propagated to the related entities. You can specify the values listed in the following table in the cascade attribute.

Table 6-7 Types of cascade attributes

Types of cascade attributesExplanation
CascadeType.ALLThe persist, remove, merge, and refresh operations are propagated to the relation destination.
CascadeType.PERSISTThe persist operation is propagated to the relation destination.
CascadeType.REMOVEThe remove operation is propagated to the relation destination.
CascadeType.MERGEThe merge operation is propagated to the relation destination.
CascadeType.REFRESHThe refresh operation is propagated to the relation destination.