PersistenceManager
s perform several actions
that affect the lifecycle state of persistence-capable instances.
Each of these actions is represented by multiple methods in the
PersistenceManager
interface: one method
that acts on a single persistence-capable object, such as
makePersistent
, and corresponding methods
that accept a collection or array of persistence-capable objects,
such as makePersistentAll
.
public Object makePersistent (Object pc); public Collection makePersistentAll (Collection pcs); public Object[] makePersistentAll (Object[] pcs);
Transitions transient instances to persistent-new, and creates managed
copies of detached objects. This action can
only be used in the context of an active transaction. On the next
flush or commit, the newly persisted instances will be inserted into
the datastore, and changes to the detached instances will be flushed to
the corresponding datastore records. If you attempt to attach an
instance whose representation has changed in the datastore since
detachment, the makePersistent
operation will
throw an exception, or the transaction in which you perform the
attachment will fail on commit, just as if a normal optimistic conflict
were detected. If the attach process fails, the RollbackOnly
flag is set on the current transaction.
For each argument, makePersistent[All]
returns
the argument instance if it was transient, or a managed copy of the
argument instance if it was detached. Thus, when attaching objects, it
is important to use the returned copies rather than continuing to
act on the detached objects.
public void deletePersistent (Object pc); public void deletePersistentAll (Collection pcs); public void deletePersistentAll (Object[] pcs);
Transitions persistent instances to persistent-deleted, or persistent-new instances to persistent-new-deleted. This action, too, can only be called during an active transaction. The given instances will be deleted from the datastore on the next flush or commit.
public void makeTransient (Object pc); public void makeTransientAll (Collection pcs); public void makeTransientAll (Object[] pcs);
This action transitions persistent instances to transient. The
instances immediately lose their association with the
PersistenceManager
and their JDO
identity. The datastore records for the instances are not modified.
This action can only be run on clean objects. If it is run on a dirty
object, a JDOUserException
is thrown.
public void makeTransactional (Object pc); public void makeTransactionalAll (Collection pcs); public void makeTransactionalAll (Object[] pcs);
Use this action to make transient instances transient-transactional, or to bring persistent-nontransactional instances into the current transaction. In the latter case, the action must be invoked during an active transaction.
public void makeNontransactional (Object pc); public void makeNontransactionalAll (Collection pcs); public void makeNontransactionalAll (Object[] pcs);
Transitions transient-clean instances to transient, and
persistent-clean instances to persistent-nontransactional. Invoking
this action on a dirty instance will result in a
JDOUserException
.
public void refresh (Object pc); public void refreshAll (Collection pcs); public void refreshAll (Object[] pcs); public void refreshAll (); public void refreshAll (JDOException je);
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.
Calling the refreshAll
method
with no parameters acts on all transactional objects in
the PersistenceManager
cache. If there is no
transaction in progress, the method is a no-op.
Calling the refreshAll
method
with a JDOException
refreshes the failed object
held by the exception, and recurses on all nested exceptions.
public void retrieve (Object pc); public void retrieveAll (Collection pcs); public void retrieveAll (Object[] pcs); public void retrieveAll (Collection pcs, boolean fgOnly); public void retrieveAll (Object[] pcs, boolean fgOnly);
Retrieving a persistent object immediately loads all of the object's
persistent fields with their datastore values. You might
use this action to make sure an instance's fields are
fully loaded before transitioning it to transient. Note,
however, that this action is not recursive. That is, if
object A has a relation to object B, then passing A to
retrieve
will load B, but will not
necessarily fill B's fields with their datastore values.
Setting fgOnly
to true will ensure that the fields
in the current fetch groups are loaded, but may not load other fields.