9.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 section 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 9‒4: Entity state
State of entity instances	Explanation
`new`	A 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.
`managed`	A state in which the entity has a persistence identity associated with the persistence context and is managed with the persistence context.
`detached`	A state in which the entity has a persistence identity that is not associated with the persistence context.
`removed`	A 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.

To Page Top

(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 9‒5: Types of operations for the entities
Operations	Explanation
`flush`	This operation applies the content of the entity object to the database.
`merge`	In this operation, the entity object that was not managed by `EntityManager` is managed by `EntityManager`.
`persist`	This operation manages and perpetuates the entity object.
`refresh`	This operation applies the database content to the entity object.
`remove`	This operation sets the entity object to the state of scheduled deletion.

To Page Top

(3) Operations and state transition for the entities

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

Figure 9‒3: Operations and state transition for the entity instances

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

Table 9‒6: Transition of entity states
Operations	State
Operations	new	managed	detached	removed
`persist`	`managed`^#1	`managed`	`managed`^#1	`managed`
`remove`	`new`	`removed`	Exception^{#2, #3}	`removed`
`merge`	Copy source `new` Copy destination `managed`	Copy source `managed` Copy destination `managed`	Copy source `detached` Copy destination `managed`	Exception^{#3, #4}
`refresh`	Exception^{#2, #4}	`managed`^#5	Exception^{#2, #4}	Exception^{#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.

For a persistence context in the transaction scope

TransactionRequiredException occurs.
For an extended persistence context

The state changes and the states are applied to the database when the next transaction is concluded.

To Page Top

(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 9‒7: Types of cascade attributes
Types of cascade attributes	Explanation
`CascadeType.ALL`	The `persist`, `remove`, `merge`, and `refresh` operations are propagated to the relation destination.
`CascadeType.PERSIST`	The `persist` operation is propagated to the relation destination.
`CascadeType.REMOVE`	The `remove` operation is propagated to the relation destination.
`CascadeType.MERGE`	The `merge` operation is propagated to the relation destination.
`CascadeType.REFRESH`	The `refresh` operation is propagated to the relation destination.

To Page Top