Detached JPA Entities

Detached entities are objects in a special state where they are not managed by an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. but still represent objects in the database. Compared to managed entities, detached objects have limited functionality:

• Many JPA methods, for example, lockjakarta.persistence.EntityManager.lock(Object,LockModeType)Lock an entity instance belonging to the persistence context, obtaining the specified lock mode ., do not accept detached objects.
• Retrieval by navigation from detached objects is not supported. You can only access persistent fields that were loaded before the object was detached.
• Changes to detached entities are not persisted to the database unless you merge them back into an EntityManager, which makes them managed again.

Detached objects are useful when an EntityManager is not available or for transferring objects between different EntityManager instances.

Explicit detach

You can detach an entity by using the detachjakarta.persistence.EntityManager.detach(Object)Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. method:

  em.detachjakarta.persistence.EntityManager.detach(Object)Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached.(employee);

The detachjakarta.persistence.EntityManager.detach(Object)Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. method throws an IllegalArgumentException if the argument is not an entity.

In addition, when a managed entity is serialized and then deserialized, the deserialized object becomes a detached entities because it is not associated with an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context.. The original serialized object is not affected.

Cascading detach

To automatically cascade a detachjakarta.persistence.EntityManager.detach(Object)Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. operation to related entities, mark the reference field with CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..DETACHjakarta.persistence.CascadeType.DETACHCascade the detach operation or CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..ALLjakarta.persistence.CascadeType.ALLCascade all operations. When you detachjakarta.persistence.EntityManager.detach(Object)Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. an entity, the operation cascades to the entities referenced by that field, which can be a single entity or a collection of entities:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity.
class Employee {
     :
    @OneToOnejakarta.persistence.OneToOneSpecifies a single-valued association to another entity class that has one-to-one multiplicity.(cascadejakarta.persistence.OneToOne.cascade(Optional) The operations that must be cascaded to the target of the association.=CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..DETACHjakarta.persistence.CascadeType.DETACHCascade the   detach   operation)
    private Address address;
     :
}

In the example above, the Employee entity has an address field that references an Address entity. Because the field is marked with CascadeType.DETACH, detaching an Employee instance also detaches the referenced Address instance. This process continues recursively to any other entities referenced with cascading enabled.

Bulk detach

The following operations detach all managed entities by clearing the persistence context of an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context.:

• Calling the closejakarta.persistence.EntityManager.close()Close an application-managed entity manager. method on an EntityManager.
• Calling the clearjakarta.persistence.EntityManager.clear()Clear the persistence context, causing all managed entities to become detached. method on an EntityManager.
• Rolling back a transaction, either by calling rollbackjakarta.persistence.EntityTransaction.rollback()Roll back the current resource transaction. or when a commitjakarta.persistence.EntityTransaction.commit()Commit the current resource transaction, writing any unflushed changes to the database. fails.

Explicit merge

You can merge a detached object back into a persistence context by using the mergejakarta.persistence.EntityManager.merge(T)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.mergejakarta.persistence.EntityManager.merge(T)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 merge method copies the state of the detached object onto a managed entity with the same identity (the same type and primary key). If a corresponding managed entity does not exist in the persistence context, a new one is created. The method returns the managed entity; the original detached object remains detached and unchanged.

The mergejakarta.persistence.EntityManager.merge(T)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 throws an IllegalArgumentException if the argument is not an entity instance or if it is a removed entity. It throws a TransactionRequiredExceptionjakarta.persistence.TransactionRequiredExceptionThrown by the persistence provider when a transaction is required but is not active. if you call it without an active transaction, because merging can modify the database.

Cascading merge

To automatically cascade a mergejakarta.persistence.EntityManager.merge(T)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. operation to related entities, mark the reference field with CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..MERGEjakarta.persistence.CascadeType.MERGECascade the merge operation or CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..ALLjakarta.persistence.CascadeType.ALLCascade all operations. When you merge the entity, the operation cascades to the entities referenced by that field, which can be a single entity or a collection of entities:

@Entityjakarta.persistence.EntityDeclares that the annotated class is an entity.
class Employee {
     :
    @OneToOnejakarta.persistence.OneToOneSpecifies a single-valued association to another entity class that has one-to-one multiplicity.(cascadejakarta.persistence.OneToOne.cascade(Optional) The operations that must be cascaded to the target of the association.=CascadeTypejakarta.persistence.CascadeTypeDefines the set of cascadable operations that are propagated to the associated entity..MERGEjakarta.persistence.CascadeType.MERGECascade the   merge   operation)
    private Address address;
     :
}

In the example above, the Employee entity has an address field that references an Address entity. Because the field is marked with CascadeType.MERGE, merging an Employee instance also merges the referenced Address instance. This process continues recursively to any other entities referenced with cascading enabled.