Detached Entity Objects

Detached entity objects are objects in a special state in which they are not managed by any EntityManagerjakarta.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 belonging to the persistence context, obtaining the specified {@linkplain LockModeType lock mode}.).
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 EntityManagerjakarta.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 Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. method:

  em.detachEntityManager.detach(entity) - JPA Method
 Evict the given managed or removed entity from the persistence
 context, causing the entity to become immediately detached.(employee);

An IllegalArgumentException is thrown by detachEntityManager.detach(entity) - JPA Method Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. if the argument is not an entity object.

Cascading Detach

Marking a reference field with CascadeTypejakarta.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..DETACHjakarta.persistence.CascadeType.DETACH - JPA Enum Constant Cascade the {@linkplain EntityManager#detach detach} operation (or CascadeTypejakarta.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..ALLjakarta.persistence.CascadeType.ALL - JPA Enum Constant Cascade all operations , which includes DETACHjakarta.persistence.CascadeType.DETACH - JPA Enum Constant Cascade the {@linkplain EntityManager#detach detach} operation ) indicates that detachEntityManager.detach(entity) - JPA Method Evict the given managed or removed entity from the persistence context, causing the entity to become immediately 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):

@Entityjakarta.persistence.Entity - JPA Annotation
 Declares that the annotated class is an entity.
class Employee {
     :
    @OneToOnejakarta.persistence.OneToOne - JPA Annotation
 Specifies a single-valued association to another entity class that
 has one-to-one multiplicity.(cascadejakarta.persistence.OneToOne.cascade - JPA Annotation Attribute
 (Optional) The operations that must be cascaded to the
 target of the association.=CascadeTypejakarta.persistence.CascadeType - JPA Enum
 Defines the set of cascadable operations that are propagated
 to the associated entity..DETACHjakarta.persistence.CascadeType.DETACH - JPA Enum Constant
 Cascade the {@linkplain EntityManager#detach 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 EntityManagerjakarta.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 new or detached entity instance into the current persistence context, resulting in, respectively, an insert or possible update when the persistence context is synchronized with the database. method:

  Employee managedEmployee = em.mergeEntityManager.merge(entity) - JPA Method
 Merge the state of the given new or detached entity instance
 into the current persistence context, resulting in, respectively,
 an insert or possible update when the persistence context is
 synchronized with the database.(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 new or detached entity instance into the current persistence context, resulting in, respectively, an insert or possible update when the persistence context is synchronized with the database. if the argument is not an instance of an entity class or it is a removed entity. A TransactionRequiredExceptionjakarta.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 CascadeTypejakarta.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..MERGEjakarta.persistence.CascadeType.MERGE - JPA Enum Constant Cascade the {@linkplain EntityManager#merge merge} operation (or CascadeTypejakarta.persistence.CascadeType - JPA Enum Defines the set of cascadable operations that are propagated to the associated entity..ALLjakarta.persistence.CascadeType.ALL - JPA Enum Constant Cascade all operations , which includes MERGEjakarta.persistence.CascadeType.MERGE - JPA Enum Constant Cascade the {@linkplain EntityManager#merge merge} operation ) indicates that mergeEntityManager.merge(entity) - JPA Method Merge the state of the given new or detached entity instance into the current persistence context, resulting in, respectively, an insert or possible update when the persistence context is synchronized with the database. operations should be cascaded automatically to entity objects that are referenced by that field (multiple entity objects can be referenced by a collection field):

@Entityjakarta.persistence.Entity - JPA Annotation
 Declares that the annotated class is an entity.
class Employee {
     :
    @OneToOnejakarta.persistence.OneToOne - JPA Annotation
 Specifies a single-valued association to another entity class that
 has one-to-one multiplicity.(cascadejakarta.persistence.OneToOne.cascade - JPA Annotation Attribute
 (Optional) The operations that must be cascaded to the
 target of the association.=CascadeTypejakarta.persistence.CascadeType - JPA Enum
 Defines the set of cascadable operations that are propagated
 to the associated entity..MERGEjakarta.persistence.CascadeType.MERGE - JPA Enum Constant
 Cascade the {@linkplain EntityManager#merge 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 >