![[Note]](images.admon/note.gif) | |
| |
An entity instance may be characterized as being new, managed, detached, or removed.
A new entity instance has no persistent identity, and is NOT yet ASSOCIATED with a persistence context.
A managed entity instance is an instance with a persistent identity that is currently ASSOCIATED with a persistence context.
A detached entity instance is an instance with a persistent identity that is NOT (or no longer) ASSOCIATED with a persistence context.
A removed entity instance is an instance with a persistent identity, ASSOCIATED with a persistence context, that is SCHEDULED for removal from the database.
Use of the cascade annotation element may be used to propagate the effect of an operation to associated entities. The cascade functionality is most typically used in parent-child relationships.
Persisting an Entity Instance
A new entity instance becomes both MANAGED and PERSISTENT by invoking the persist method on it or by cascading the persist operation.
The semantics of the persist operation, applied to an entity X are as follows:
If X is a NEW entity, it becomes MANAGED. The entity X will be entered into the database at or before transaction commit or as a result of the flush operation.
If X is a preexisting MANAGED entity, it is IGNORED by the persist operation. However, the persist operation is cascaded to entities referenced by X, if the relationships from X to these other entities is annotated with the cascade=PERSIST or cascade=ALL annotation element value or specified with the equivalent XML descriptor element.
If X is a REMOVED entity, it becomes MANAGED.
If X is a DETACHED object, the EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.
For all entities Y referenced by a relationship from X, if the relationship to Y has been annotated with the cascade element value cascade=PERSIST or cascade=ALL, the persist operation is applied to Y.
Removal
A MANAGED entity instance becomes REMOVED by invoking the remove method on it or by cascading the remove operation.
The semantics of the remove operation, applied to an entity X are as follows:
If X is a NEW entity, it is IGNORED by the remove operation. However, the remove operation is cascaded to entities referenced by X, if the relationship from X to these other entities is annotated with the cascade=REMOVE or cascade=ALL annotation element value.
If X is a MANAGED entity, the remove operation causes it to become REMOVED. The remove operation is cascaded to entities referenced by X, if the relationships from X to these other entities is annotated with the cascade=REMOVE or cascade=ALL annotation element value.
If X is a DETACHED entity, an IllegalArgumentException will be thrown by the remove operation (or the transaction commit will fail).
If X is a REMOVED entity, it is IGNORED by the remove operation.
A removed entity X will be removed from the database at or before transaction commit or as a result of the flush operation.
After an entity has been removed, its state (except for generated state) will be that of the entity at the point at which the remove operation was called.
Synchronization to the Database
The state of persistent entities is synchronized to the database at transaction commit. This synchronization involving writing to the database any updates to persistent entities and their relationships as speci fied above.
An update to the state of an entity includes both the assignment of a new value to a persistent property or field of the entity as well as the modification of a mutable value of a persistent property or field.
Synchronization to the database DOES NOT involve a refresh of any managed entities unless the refresh operation is EXPLICITLY invoked on those entities.
Bidirectional relationships between managed entities will be persisted based on references held by the owning side of the relationship. It is the developer's responsibility to keep the in-memory references held on the owning side and those held on the inverse side consistent with each other when they change. In the case of unidirectional one-to-one and one-to-many relationships, it is the developer's responsibility to insure that the semantics of the relationships are adhered to.
It is particularly important to ensure that changes to the inverse side of a relationship result in appropriate updates on the owning side, so as to ensure the changes are not lost when they are synchronized to the database.
The persistence provider runtime is permitted to perform synchronization to the database at other times as well when a transaction is active. The flush method can be used by the application to FORCE synchronization. It applies to entities associated with the persistence context. The EntityManager and Query setFlushMode methods can be used to control synchronization semantics. If FlushModeType.COMMIT is specified, flushing will occur at transaction commit; the persistence provider is permitted, but not required, to perform to flush at other times. If there is no transaction active, the persistence provider must not flush to the database.
The semantics of the flush operation, applied to an entity X are as follows:
If X is a MANAGED entity, it is SYNCHRONIZED to the database.
For all entities Y referenced by a relationship from X, if the relationship to Y has been annotated with the cascade element value cascade=PERSIST or cascade=ALL, the persist operation is applied to Y.
For any entity Y referenced by a relationship from X, where the relationship to Y has NOT been annotated with the cascade element value cascade=PERSIST or cascade=ALL:
If Y is NEW or REMOVED, an IllegalStateException will be thrown by the flush operation (and the transaction rolled back) or the transaction commit will fail.
If Y is DETACHED, the semantics depend upon the ownership of the relationship. If X owns the relationship, any changes to the relationship are synchronized with the database; otherwise, if Y owns the relationships, the behavior is undefined.
If X is a REMOVED entity, it is REMOVED from the database. No cascade options are relevant.
