Detached Entity Objects

Detached entity objects are objects in a special state in which they are not managed by any EntityManagerjavax.persistence.EntityManager - JPA Interface Interface 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. lockEntityManager.lock(entity,lockMode) - JPA Method Lock 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 Cascading Detach Bulk Detach Explicit Merge Cascading Merge

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 EntityManagerjavax.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context..

In addition, in JPA 2 we can detach an entity object by using the detachEntityManager.detach(entity) - JPA Method Remove the given entity from the persistence context, causing a managed entity to become detached. method:

  em.detachEntityManager.detach(entity) - JPA Method
 Remove the given entity from the persistence context, causing
 a managed entity to become detached.(employee);

An IllegalArgumentException is thrown by detachEntityManager.detach(entity) - JPA Method Remove 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 Enum Defines the set of cascadable operations that are propagated to the associated entity..DETACHjavax.persistence.CascadeType.DETACH - JPA Enum Constant Cascade detach operation (or CascadeTypejavax.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..ALLjavax.persistence.CascadeType.ALL - JPA Enum Constant Cascade all operations , which includes DETACHjavax.persistence.CascadeType.DETACH - JPA Enum Constant Cascade detach operation ) indicates that detachEntityManager.detach(entity) - JPA Method Remove 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 Annotation
 Specifies that the class is an entity.
class Employee {
     :
    @OneToOnejavax.persistence.OneToOne - JPA Annotation
 Specifies 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 Enum
 Defines the set of cascadable operations that are propagated
 to the associated entity..DETACHjavax.persistence.CascadeType.DETACH - JPA Enum Constant
 Cascade 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 EntityManagerjavax.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context.'s persistence context and detach all managed entity objects:

Invocation of the closeEntityManager.close() - JPA Method Close an application-managed entity manager. method, which closes an EntityManager.
Invocation of the clearEntityManager.clear() - JPA Method Clear 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 rollbackEntityTransaction.rollback() - JPA Method Roll back the current resource transaction. or by a commitEntityTransaction.commit() - JPA Method Commit 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 mergeEntityManager.merge(entity) - JPA Method Merge the state of the given entity into the current persistence context. method:

  Employee managedEmployee = em.mergeEntityManager.merge(entity) - JPA Method
 Merge 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 mergeEntityManager.merge(entity) - JPA Method Merge 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 TransactionRequiredExceptionjavax.persistence.TransactionRequiredException - JPA Exception Thrown 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 Enum Defines the set of cascadable operations that are propagated to the associated entity..MERGEjavax.persistence.CascadeType.MERGE - JPA Enum Constant Cascade merge operation (or CascadeTypejavax.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..ALLjavax.persistence.CascadeType.ALL - JPA Enum Constant Cascade all operations , which includes MERGEjavax.persistence.CascadeType.MERGE - JPA Enum Constant Cascade merge operation ) indicates that mergeEntityManager.merge(entity) - JPA Method Merge 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 Annotation
 Specifies that the class is an entity.
class Employee {
     :
    @OneToOnejavax.persistence.OneToOne - JPA Annotation
 Specifies 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 Enum
 Defines the set of cascadable operations that are propagated
 to the associated entity..MERGEjavax.persistence.CascadeType.MERGE - JPA Enum Constant Cascade 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).

< Advanced Topics ^ Advanced Topics Locking >