Detached Entity Objects
Detached entity objects are objects in a special state in which they are not managed by any EntityManager
javax.persistence.EntityManager - JPA InterfaceInterface used to interact with the persistence context. 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
EntityManager.lock(entity,lockMode) - JPA MethodLock an entity instance that is contained in the persistence context with the specified lock mode type.). - 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.EntityManager - JPA InterfaceInterface used to interact with the persistence context..
In addition, in JPA 2 we can detach an entity object by using the detach
EntityManager.detach(entity) - JPA MethodRemove the given entity from the persistence context, causing a managed entity to become detached. method:
em.detachEntityManager.detach(entity) - JPA MethodRemove the given entity from the persistence context, causing a managed entity to become detached.(employee);
An IllegalArgumentException
is thrown by detach
EntityManager.detach(entity) - JPA MethodRemove the given entity from the persistence context, causing a managed entity to become detached. if the argument is not an entity object.
Cascading Detach
Marking a reference field with CascadeTypejavax.persistence.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated
to the associated entity..DETACHjavax.persistence.CascadeType.DETACH - JPA Enum ConstantCascade detach operation
(or CascadeTypejavax.persistence.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated
to the associated entity..ALLjavax.persistence.CascadeType.ALL - JPA Enum ConstantCascade all operations
, which includes DETACHjavax.persistence.CascadeType.DETACH - JPA Enum ConstantCascade detach operation
) indicates that detach
EntityManager.detach(entity) - JPA MethodRemove the given entity from the persistence context, causing a managed entity to become detached. 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.Entity - JPA AnnotationSpecifies that the class is an entity. class Employee { : @OneToOnejavax.persistence.OneToOne - JPA AnnotationSpecifies a single-valued association to another entity that has one-to-one multiplicity.(cascadejavax.persistence.OneToOne.cascade - JPA Annotation Attribute(Optional) The operations that must be cascaded to the target of the association.=CascadeTypejavax.persistence.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated to the associated entity..DETACHjavax.persistence.CascadeType.DETACH - JPA Enum ConstantCascade detach operation) 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.EntityManager - JPA InterfaceInterface used to interact with the persistence context.'s persistence context and detach all managed entity objects:
- Invocation of the closeEntityManager.close() - JPA MethodClose an application-managed entity manager. method, which closes an
EntityManager
.
- Invocation of the clearEntityManager.clear() - JPA MethodClear the persistence context, causing all managed entities to become detached. method, which clears an
EntityManager
's persistence context. - Rolling back a transaction - either by invocation of
rollback
EntityTransaction.rollback() - JPA MethodRoll back the current resource transaction. or by acommit
EntityTransaction.commit() - JPA MethodCommit the current resource transaction, writing any unflushed changes to the database. failure.
Explicit Merge
Detached objects can be attached to any EntityManager by using the merge
EntityManager.merge(entity) - JPA MethodMerge the state of the given entity into the current persistence context. method:
Employee managedEmployee = em.mergeEntityManager.merge(entity) - JPA MethodMerge the state of the given entity into the current persistence context.(detachedEmployee);
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
EntityManager.merge(entity) - JPA MethodMerge the state of the given entity into the current persistence context. if the argument is not an instance of an entity class or it is a removed entity. A TransactionRequiredException
javax.persistence.TransactionRequiredException - JPA ExceptionThrown by the persistence provider when a transaction is required but is not active. 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.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated
to the associated entity..MERGEjavax.persistence.CascadeType.MERGE - JPA Enum ConstantCascade merge operation
(or CascadeTypejavax.persistence.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated
to the associated entity..ALLjavax.persistence.CascadeType.ALL - JPA Enum ConstantCascade all operations
, which includes MERGE
javax.persistence.CascadeType.MERGE - JPA Enum ConstantCascade merge operation) indicates that merge
EntityManager.merge(entity) - JPA MethodMerge the state of the given entity into the current persistence context. 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.Entity - JPA AnnotationSpecifies that the class is an entity. class Employee { : @OneToOnejavax.persistence.OneToOne - JPA AnnotationSpecifies a single-valued association to another entity that has one-to-one multiplicity.(cascadejavax.persistence.OneToOne.cascade - JPA Annotation Attribute(Optional) The operations that must be cascaded to the target of the association.=CascadeTypejavax.persistence.CascadeType - JPA EnumDefines the set of cascadable operations that are propagated to the associated entity..MERGEjavax.persistence.CascadeType.MERGE - JPA Enum ConstantCascade merge operation) 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).