2.
Entity Lifecycle Management

EntityManagers perform several actions that affect the
lifecycle state of entity instances.

public void persist(Object entity);

Transitions new instances to managed. On the next flush or commit, the newly
persisted instances will be inserted into the datastore.

For a given entity A, the persist
method behaves as follows:

If A is a new entity, it becomes managed.

If A is an existing managed entity, it is ignored. However,
the persist operation cascades as defined below.

If A is a removed entity, it becomes managed.

If A is a detached entity, an
IllegalArgumentException is thrown.

The persist operation recurses on all relation fields of A
whose cascades include
CascadeType.PERSIST.

This action can only be used in the context of an active transaction.

public void remove(Object entity);

Transitions managed instances to removed. The instances will be deleted from the
datastore on the next flush or commit. Accessing a removed entity has undefined
results.

For a given entity A, the remove
method behaves as follows:

If A is a new entity, it is ignored. However, the remove
operation cascades as defined below.

If A is an existing managed entity, it becomes removed.

If A is a removed entity, it is ignored.

If A is a detached entity, an
IllegalArgumentException is thrown.

The remove operation recurses on all relation fields of A
whose cascades include
CascadeType.REMOVE.

This action can only be used in the context of an active transaction.

public void refresh(Object entity);

Use the refresh action to make sure the persistent
state of an instance is synchronized with the values in the datastore.
refresh is intended for long-running optimistic
transactions in which there is a danger of seeing stale data.

For a given entity A, the refresh
method behaves as follows:

If A is a new entity, it is ignored. However, the refresh
operation cascades as defined below.

If A is an existing managed entity, its state is refreshed
from the datastore.

If A is a removed entity, it is ignored.

If A is a detached entity, an
IllegalArgumentException is thrown.

The refresh operation recurses on all relation fields of A
whose cascades include
CascadeType.REFRESH.

public Object merge(Object entity);

A common use case for an application running in a servlet or application server
is to "detach" objects from all server resources, modify them, and then "attach"
them again. For example, a servlet might store persistent data in a user session
between a modification based on a series of web forms. Between each form
request, the web container might decide to serialize the session, requiring that
the stored persistent state be disassociated from any other resources.
Similarly, a client/server application might transfer persistent objects to a
client via serialization, allow the client to modify their state, and then have
the client return the modified data in order to be saved. This is sometimes
referred to as the data transfer object or value
object pattern, and it allows fine-grained manipulation of data
objects without incurring the overhead of multiple remote method invocations.

JPA provides support for this pattern by automatically detaching
entities when they are serialized or when a persistence context ends (see
Section 3, “
Persistence Context
” for an exploration of
persistence contexts). The JPA merge API
re-attaches detached entities. This allows you to detach a persistent instance,
modify the detached instance offline, and merge the instance back into an
EntityManager (either the same one that detached the
instance, or a new one). The changes will then be applied to the existing
instance from the datastore.

A detached entity maintains its persistent identity, but cannot load additional
state from the datastore. Accessing any persistent field or property that was
not loaded at the time of detachment has undefined results. Also, be sure not to
alter the version or identity fields of detached instances if you plan on
merging them later.

The merge method returns a managed copy of the given
detached entity. Changes made to the persistent state of the detached entity are
applied to this managed instance. Because merging involves changing persistent
state, you can only merge within a transaction.

If you attempt to merge an instance whose representation has changed in the
datastore since detachment, the merge operation will throw an exception, or the
transaction in which you perform the merge will fail on commit, just as if a
normal optimistic conflict were detected.

Note

OpenJPA offers enhancements to JPA detachment functionality,
including additional options to control which fields are detached. See
Section 1, “
Detach and Attach
” in the Reference Guide for details.

For a given entity A, the merge
method behaves as follows:

If A is a detached entity, its state is copied into existing
managed instance A' of the same entity identity, or a new
managed copy of A is created.

If A is a new entity, a new managed entity A'
is created and the state of A is copied into
A'.

If A is an existing managed entity, it is ignored. However,
the merge operation still cascades as defined below.

If A is a removed entity, an
IllegalArgumentException is thrown.

The merge operation recurses on all relation fields of A
whose cascades include
CascadeType.MERGE.

READ: Other transactions may concurrently read the object,
but cannot concurrently update it.

WRITE: Other transactions cannot concurrently read or write
the object. When a transaction is committed that holds WRITE locks on any
entites, those entites will have their version incremented even if the entities
themselves did not change in the transaction.