EntityManager
s perform several actions
that affect the lifecycle state of entity instances.
public void persist (Object entity);
The above method transitions new instances to managed instances. 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);
The above method transitions managed instances to removed instances. 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
method 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 remove 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.
EJB persistence provides support for this pattern by automatically
detaching entities when they are serialized or when a persistence
context ends (see
Section 7.3, “Persistence Context” for an
exploration of persistence contexts). The EJB persistence
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.
Note | |
---|---|
Be sure to not 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 | |
---|---|
Kodo offers enhancements to EJB persistence detachment functionality, including additional options to control which fields are detached. See Section 11.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
.
public void lock (Object entity, LockModeType mode);
This method locks the given entity using the named mode. The
javax.persistence.LockModeType
enum
defines two modes:
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.
Note | |
---|---|
Kodo has additional APIs for controlling object locking. See Section 9.4, “Object Locking” in the Reference Guide for details. |
The following diagram illustrates the lifecycle of an entity with respect to the APIs presented in this section.