589 words

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:

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:

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 operation
See 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 operations
See JavaDoc Reference Page...
, which includes DETACHCascadeType.DETACHenum constantCascade detach operation
See 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):

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:

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:

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 operation
See 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 operations
See JavaDoc Reference Page...
, which includes MERGECascadeType.MERGEenum constantCascade merge operation
See 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):

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).


This documentation explains how to use JPA in the context of the ObjectDB Object Database but mostly relevant
also for ORM JPA implementations, such as Hibernate (and HQL), EclipseLink, TopLink, OpenJPA and DataNucleus.
ObjectDB is not an ORM JPA implementation but an Object Database (ODBMS) for Java with built in JPA 2 support.