Detached Entity Objects
Detached entity objects are objects in a special state in which they are not managed by any EntityManager
javax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... but still represent objects in the database. Compared to managed entity objects, detached objects are limited in functionality:
- Many JPA methods do not accept detached objects (e.g.
lock
lock(entity, lockMode)EntityManager's methodLock an entity instance that is contained in the persistence context with the specified lock mode type.See JavaDoc Reference Page...). - Retrieval by navigation from detached objects is not supported, so only persistent fields that have been loaded before detachment should be used.
- Changes to detached entity objects are not stored in the database unless modified detached objects are merged back into an
EntityManager
to become managed again.
Detached objects are useful in situations in which an EntityManager
is not available and for transferring objects between different EntityManager
instances.
This page covers the following topics:
Explicit Detach
When a managed entity object is serialized and then deserialized, the deserialized entity object (but not the original serialized object) is constructed as a detached entity object since is not associated with any EntityManager
javax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page....
In addition, in JPA 2 we can detach an entity object by using the detach
detach(entity)EntityManager's methodRemove the given entity from the persistence context, causing a managed entity to become detached.See JavaDoc Reference Page... method:
em.detachdetach(entity)EntityManager's methodRemove the given entity from the persistence context, causing a managed entity to become detached.See JavaDoc Reference Page...(employee);
An IllegalArgumentException
is thrown by detach
detach(entity)EntityManager's methodRemove the given entity from the persistence context, causing a managed entity to become detached.See JavaDoc Reference Page... if the argument is not an entity object.
Cascading Detach
Marking a reference field with CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....DETACHCascadeType.DETACHenum constantCascade detach operationSee JavaDoc Reference Page...
(or CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....ALLCascadeType.ALLenum constantCascade all operationsSee JavaDoc Reference Page...
, which includes DETACHCascadeType.DETACHenum constantCascade detach operationSee JavaDoc Reference Page...
) indicates that detach
detach(entity)EntityManager's methodRemove the given entity from the persistence context, causing a managed entity to become detached.See JavaDoc Reference Page... operations should be cascaded automatically to entity objects that are referenced by that field (multiple entity objects can be referenced by a collection field):
@Entityjavax.persistence.EntityJPA annotationSpecifies that the class is an entity.See JavaDoc Reference Page... class Employee { : @OneToOnejavax.persistence.OneToOneJPA annotationDefines a single-valued association to another entity that has one-to-one multiplicity.See JavaDoc Reference Page...(cascadeOneToOne.cascadeannotation element(Optional) The operations that must be cascaded to the target of the association.See JavaDoc Reference Page...=CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....DETACHCascadeType.DETACHenum constantCascade detach operationSee JavaDoc Reference Page...) private Address address; : }
In the example above, the Employee
entity class contains an address
field that references an instance of Address
, which is another entity class. Due to the CascadeType.DETACH
setting, when an Employee
instance is detached the operation is automatically cascaded to the referenced Address
instance, which is then automatically detached as well. Cascading may continue recursively when applicable (e.g. to entity objects that the Address
object references, if any).
Bulk Detach
The following operations clear the entire EntityManager
javax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page...'s persistence context and detach all managed entity objects:
- Invocation of the closeclose()EntityManager's methodClose an application-managed entity manager.See JavaDoc Reference Page... method, which closes an
EntityManager
.
- Invocation of the clearclear()EntityManager's methodClear the persistence context, causing all managed entities to become detached.See JavaDoc Reference Page... method, which clears an
EntityManager
's persistence context. - Rolling back a transaction - either by invocation of
rollback
rollback()EntityTransaction's methodRoll back the current resource transaction.See JavaDoc Reference Page... or by acommit
commit()EntityTransaction's methodCommit the current resource transaction, writing any unflushed changes to the database.See JavaDoc Reference Page... failure.
Explicit Merge
Detached objects can be attached to any EntityManager by using the merge
merge(entity)EntityManager's methodMerge the state of the given entity into the current persistence context.See JavaDoc Reference Page... method:
em.mergemerge(entity)EntityManager's methodMerge the state of the given entity into the current persistence context.See JavaDoc Reference Page...(employee);
The content of the specified detached entity object is copied into an existing managed entity object with the same identity (i.e. same type and primary key). If the EntityManager
does not manage such an entity object yet a new managed entity object is constructed. The detached object itself, however, remains unchanged and detached.
An IllegalArgumentException
is thrown by merge
merge(entity)EntityManager's methodMerge the state of the given entity into the current persistence context.See JavaDoc Reference Page... if the argument is not an instance of an entity class or it is a removed entity. A TransactionRequiredException
javax.persistence.TransactionRequiredExceptionJPA exceptionThrown by the persistence provider when a transaction is required but is not active.See JavaDoc Reference Page... is thrown if there is no active transaction when merge
is called because operations that might modify the database require an active transaction.
Cascading Merge
Marking a reference field with CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....MERGECascadeType.MERGEenum constantCascade merge operationSee JavaDoc Reference Page...
(or CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....ALLCascadeType.ALLenum constantCascade all operationsSee JavaDoc Reference Page...
, which includes MERGE
CascadeType.MERGEenum constantCascade merge operationSee JavaDoc Reference Page...) indicates that merge
merge(entity)EntityManager's methodMerge the state of the given entity into the current persistence context.See JavaDoc Reference Page... operations should be cascaded automatically to entity objects that are referenced by that field (multiple entity objects can be referenced by a collection field):
@Entityjavax.persistence.EntityJPA annotationSpecifies that the class is an entity.See JavaDoc Reference Page... class Employee { : @OneToOnejavax.persistence.OneToOneJPA annotationDefines a single-valued association to another entity that has one-to-one multiplicity.See JavaDoc Reference Page...(cascadeOneToOne.cascadeannotation element(Optional) The operations that must be cascaded to the target of the association.See JavaDoc Reference Page...=CascadeTypejavax.persistence.CascadeTypeJPA enumDefines the set of cascadable operations that are propagated to the associated entity.See JavaDoc Reference Page....MERGECascadeType.MERGEenum constantCascade merge operationSee JavaDoc Reference Page...) private Address address; : }
In the example above, the Employee
entity class contains an address
field that references an instance of Address
, which is another entity class. Due to the CascadeType.MERGE
setting, when an Employee
instance is merged the operation is automatically cascaded to the referenced Address
instance, which is then automatically merged as well. Cascading may continue recursively when applicable (e.g. to entity objects that the Address
object references, if any).