Detached Entity Objects

Detached entity objects are objects in a special state in which they are not managed by any EntityManagerjavax.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. locklock(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.

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.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 detachdetach(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 detachdetach(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 detachdetach(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 EntityManagerjavax.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 rollbackrollback()EntityTransaction's methodRoll back the current resource transaction.See JavaDoc Reference Page... or by a commitcommit()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 mergemerge(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 mergemerge(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 TransactionRequiredExceptionjavax.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 MERGECascadeType.MERGEenum constantCascade merge operationSee JavaDoc Reference Page...) indicates that mergemerge(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).